econmethods 3.0.6.2__tar.gz → 3.1.0.0__tar.gz

{econmethods-3.0.6.2 → econmethods-3.1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: econmethods
-Version: 3.0.6.2
+Version: 3.1.0.0
 Summary: A python package implementing various econometrical tests and estimators
 Home-page: https://github.com/NaturionBG/econmethods
 Author: NaturionBG
@@ -14,19 +14,12 @@ Requires-Dist: statsmodels>=0.14.5
 Requires-Dist: numpy>=2.3.5
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: scipy>=1.16.3
+Requires-Dist: dask>=2025.9.1
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
-Dynamic: description
 Dynamic: home-page
 Dynamic: license
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
-
-* econmethods
-
-A library made specifically for an econometrics project. 
-Contains implementations of various estimators and tests.
-
-The library is not made by a professional, hence, the implemented methods may require a very scecific data struture.

econmethods-3.1.0.0/README.md

@@ -0,0 +1,17 @@
+# <b>econmethods</b>
+
+# A library made specifically for an econometrics project. 
+<h1>Contains:</h1>
+<ul>
+  <li>The one-way CIPS test, accessible via the CipsTest class.</li>
+  <li>The two-way Hausman test, accessible via the Hausman class</li>
+  <li>A universal class for estimating a first-order Error Correction Model, accessible via the FECM class. Hyperparameters include:</li>
+  <ol>
+    <li> turn on/off automatic recursive removal of insignificant coefficients. The significance level is set by the user.</li>
+    <li> turn on/off the addition of constants for both the long-run model and the short-run model.</li>
+    <li> choose the kind of effects for the long run model (RE/FE), choose the ECM estimation strategy (MG, CCEP, CCEMG)</li>
+    <li> augment with a trend (if exists in the user's data), choose the variables that make up the cointegrating vector, or add static variables into the ECM estimation, if economic theory suggests that such insertion is plausible. Such variables will be inserted into the estimation in their original levels (or log-levels), not in their first differences. </li>
+  </ol>
+  <li>The Cross-Sectional Dependence test, accessible via the CDTest class.</li>
+  <li>The Slope Homogeneity F-test, accessible via the SlopeHomogeneityF class.</li>
+</ul>

{econmethods-3.0.6.2 → econmethods-3.1.0.0}/econmethods/Lib.py

@@ -7,14 +7,15 @@ from math import floor
 import importlib.resources as resources
 from statsmodels.regression.mixed_linear_model import MixedLM
 from statsmodels.stats.diagnostic import het_goldfeldquandt
-from typing import Any
+from typing import Any, Literal
+import dask
 
 def read_critical_values(sheet: str) -> pd.DataFrame:
     xlsx_path = resources.files("econmethods") / "CADF_Crit_Values.xlsx"
     df = pd.read_excel(xlsx_path, sheet_name=sheet, index_col=0)
     return df
 
-class CipsTest:
+class CIPS:
   '''
   Implementation of the standard Cross-Sectionally Augmented Dickey-Fuller 
   procedure to test for non-stationarity I(1) in panel data. Works only with a linear trend.
@@ -25,7 +26,7 @@ class CipsTest:
   PARAMETERS:
   ----------
   ------
-  - *df*: A standart Pandas DataFrame containing panelized data. \n
+  - *df*: A standard Pandas DataFrame containing panelized data. \n
     Ensure that the DataFrame contains the following columns in this exact order: \n
     0 - a column of spatial units. Must contain homogenous data, e.g. only countries, companies, regions, etc. \n
     1 - temporal column. Must contain homogenous data, e.g. only years, months, quarters, etc. \n
@@ -36,7 +37,7 @@ class CipsTest:
   
   - *trend*: State whether your ADF model has a trend or not. Will be used to determine the test critical value.
   
-  - *poly_trend*: State whether your target variable has a ditinct polynomial trend. \n
+  - *poly_trend*: State whether your target variable has a distinct polynomial trend. \n
     If a value bigger than 1 is entered, the test will detrend the target variable to get a robust result.
   
   - *intercept*: State whether ADF model has an intercept or not. Will be used to determine the test critical value.
@@ -45,14 +46,14 @@ class CipsTest:
     the test will choose the best lag amount from 1 to n_lags based on AIC (Akaike Information Criterion) 
     
   - *level*: Value of significance to conduct the test at (in %%). Only 5 and 1% are allowed.
-  - *log_target*: Specify whether the test shall aplly a natural logarithm to your target variable. Defaults to True.
+  - *log_target*: Specify whether the test shall apply a natural logarithm to your target variable. Defaults to True.
   -----------------------------
   RETURNS:
   --
-  via instance.verdict() -> None: Prints the verdict of the test based on the parameters set by the user.
+  + **via instance.verdict() -> None**: Prints the verdict of the test based on the parameters set by the user.
   '''
   def __init__(self, df: pd.DataFrame, T: int, N: int, trend: bool =  False, poly_trend: int = 1, intercept: bool = False, n_lags: int = 2, level: int = 5, log_target: bool = True) -> None:
-    CipsTest.__build_tables()
+    CIPS.__build_tables()
     self.__df = df
     self.__L = 1
     self.__T = T
@@ -98,19 +99,19 @@ class CipsTest:
   def get_table(self) -> pd.DataFrame:
     if not self.__trend and not self.__C:
       if self.__alpha == 0.01:
-        return CipsTest.NTNC_1P
+        return CIPS.NTNC_1P
       else:
-        return CipsTest.NTNC_5P
+        return CIPS.NTNC_5P
     if not self.__trend and self.__C:
       if self.__alpha == 0.01:
-        return CipsTest.NTC_1P
+        return CIPS.NTC_1P
       else:
-        return CipsTest.NTC_5P
+        return CIPS.NTC_5P
     if self.__trend and self.__C:
       if self.__alpha == 0.01:
-        return CipsTest.TC_1P
+        return CIPS.TC_1P
       else:
-        return CipsTest.TC_5P
+        return CIPS.TC_5P
   
   def get_critical_value(self) -> float:
     dct = {}
@@ -187,7 +188,6 @@ class CipsTest:
   def __del__(self) -> None:
     pass
 
-
 class Hausman:
   '''
   Implementation of the Hausman procedure to test whether it is more feasible to used random effects against fixed effects.
@@ -790,3 +790,240 @@ class SlopeHomogeneityF:
   def __del__(self) -> None:
     pass
 
+def compute_adf_moments(T: int, mode: Literal['n', 'c', 'ct'] =  'n', simulation_count: int = 50_000, lag_depth: int = 1, seed: int = 42, chunksize: int = 500, dask_scheduler: Literal['threads', 'processes', 'synchronous'] = 'processes') -> dict:
+  '''
+  IPS test backbone function for computing the ADF distribution Variance and Mean for correction.
+  ---
+  PARAMETERS:
+  ---
+  + **T:** the amount of time periods in your data.
+  + **mode:** choose from **["n", "c", "ct"]** for No augmentation, Augmentation with a Const., Augmentation with a const. and a Linear Trend. *Defaults to "n"*.
+  + **simulation_count:** the amount of Monte-Carlo replications. *Defaults to 50_000, as suggested by Im, Pesaran, Shin (2003)*.
+  + **lag_depth:** the depth of the dy lag. At lag_depth = 0 the regression becomes the DF regression. *Defaults to 1*.
+  + **seed:** input the random seed for NumPy. *Defaults to 42.*
+  + **chunksize:** the function utilizes Dask for parallel computation. Each worker computes (chunksize) t-statistics. For the default simulation_count = 50_000, changing this parameter is ill-advised. *Defaults to 500*.
+  + **scheduler:** the function utilizes Dask for parallel computation. This parameter sets a scheduler from **["threads", "processes", "synchronous"]**. Generally, setting a scheduler other than "processes" is ill-advised, if said scheduler is supported by the system. *Defaults to "processes"*.
+  ---
+  
+  RETURNS:
+  ---
+  + **a dictionary of structure: {"E":mean_of_t_statistic, "Var":variance_of_t_statistic}**. Both statistics represent the INDIVIDUAL ADF/DF t-statistics under H0: beta_i = 0
+  
+  '''
+  
+  dask_scheduler = dask_scheduler.lower()
+  
+  mode = mode.lower()
+  
+  assert mode in ['n', 'c', 'ct']
+  assert dask_scheduler in ['threads', 'processes', 'synchronous']
+  
+  @dask.delayed
+  def get_t(deltas_chunk: np.ndarray, lag_depth: int, T: int, mode: str) -> list[float]:
+    
+    container = []    
+    
+    for j in range(deltas_chunk.shape[0]):
+      deltas = deltas_chunk[j, :]
+      y = np.concatenate([[0.0], np.cumsum(deltas)])
+      target = np.concatenate([[np.nan], deltas])
+      
+      adf = pd.DataFrame(np.concatenate([target.reshape(-1, 1), y.reshape(-1, 1)], axis=1), columns=['dy', 'y'])
+      
+      for lag in range(0, lag_depth+1):
+        if lag == 0:
+          adf['y_(t-1)'] = adf['y'].shift(1)
+        else:
+          adf[f'dy_(t-{lag})'] = adf['dy'].shift(lag)
+      
+      adf = adf.drop(columns = ['y'])
+      
+      if 't' in mode:
+        adf['t'] = np.arange(-lag_depth, T+1)
+      
+      if 'c' in mode:
+        adf = sm.add_constant(adf)
+        
+      adf = adf.iloc[lag_depth+1:, :].reset_index(drop=True)
+      
+      t = sm.OLS(adf.loc[:, 'dy'], adf.drop(columns='dy')).fit().tvalues['y_(t-1)']
+      container.append(t)
+
+    return container
+  
+  all_deltas = np.random.default_rng(seed=seed).standard_normal(size=(simulation_count, T + lag_depth))
+
+  t_container = [get_t(all_deltas[i:i+chunksize, :], lag_depth, T, mode) for i in range(0, simulation_count, chunksize)]  
+  
+  out = np.concatenate(dask.compute(*t_container, scheduler=dask_scheduler))
+  return {'E': float(out.mean()), 'Var':float(out.var(ddof=1))}
+
+class IPS:
+  '''
+  Implementation of the Im-Pesaran-Shin (2003)
+  procedure to test for non-stationarity I(1) in panel data.
+  ----
+  The hypotheses are as follows:
+  - *H0*: The Target variable is I(1)
+  - *H1*: The Target variable is I(0)\n
+  - *Rejection is left-tailed*
+  PARAMETERS:
+  ----------
+  ------
+  - *df*: A standard Pandas DataFrame containing panelized data. \n
+    Ensure that the DataFrame contains the following columns in this exact order: \n
+    0 - a column of spatial units. Must contain homogenous data, e.g. only countries, companies, regions, etc. \n
+    1 - temporal column. Must contain homogenous data, e.g. only years, months, quarters, etc. \n
+    2 - target variable. Must not contain NaN Values. An Error will be raised otherwise. \n
+  
+  - *trend*: State whether your ADF model has a trend or not.
+  
+  - *poly_trend*: State whether your target variable has a distinct polynomial trend. \n
+    If a value bigger than 1 is entered, the test will detrend the target variable to get a robust result.
+  
+  - *intercept*: State whether ADF model has an intercept or not.
+  
+  - *n_lags*: Determine the amount of lags in the Augmented Dickey-Fuller regression.
+    
+  - *level*: Value of significance to conduct the test at (in %%).
+  
+  - *log_target*: Specify whether the test shall apply a natural logarithm to your target variable. Defaults to True.
+  
+  - *n_reps*: the amount of Monte-Carlo replications used for Dickey-Fuller moments estimation. *Defaults to 50_000, as suggested by Im, Pesaran, Shin (2003)*.
+  
+  - *seed*: input the random seed for NumPy. This seed is used for the ADF Monte-Carlo simulations. *Defaults to 42.*
+  
+  - *chunksize*: the ADF Monte-Carlo simulations utilize Dask for parallel computation. Each worker computes (chunksize) t-statistics. For the default simulation_count = 50_000, changing this parameter is ill-advised. *Defaults to 500*.
+  
+  - *dask_scheduler*: the ADF Monte-Carlo simulations utilize Dask for parallel computation. This parameter sets a scheduler from **["threads", "processes", "synchronous"]**. Generally, setting a scheduler other than "processes" is ill-advised, if said scheduler is supported by the system. *Defaults to "processes"*.
+  -----------------------------
+  RETURNS:
+  --
+  + **via instance.verdict() -> None**: Prints the verdict of the test based on the parameters set by the user.
+  + **PLEASE NOTE** that the test is computationally expensive due to Monte-Carlo simulations (approx. 20 - 35 seconds per each unique value of T, if panels are unbalanced)
+  + **Due to computational complexity, it is highly advised that one does not run any methods, except for instance.verdict() 
+  unless they specifically wish to observe the ADF Mean & Variance point-estimates or the test Z-Score**
+
+  '''
+  def __init__(self, df: pd.DataFrame, trend: bool =  False, poly_trend: int = 1, intercept: bool = False, n_lags: int = 2, level: int = 5, log_target: bool = True, n_reps: int = 50_000, seed: int = 42, chunksize: int = 500, dask_scheduler: Literal['threads', 'processes', 'synchronous'] = 'processes') -> None:
+    self.__df = df.copy(deep=True)
+    self.__poly = poly_trend
+    self.__alpha = level/100
+    self.__df = self.__df.rename(columns={self.__df.columns[0]:'SpUnit', self.__df.columns[1]:'time', self.__df.columns[2]:'target'})
+    if log_target:
+      self.__df['target'] = np.log(self.__df['target'])
+
+    self.__trend = trend
+    self.__C = intercept
+    self.__n_lags = n_lags
+    self.__seed = seed
+    self.__chunksize = chunksize
+    self.__scheduler = dask_scheduler
+    self.__n_reps = n_reps
+
+    self.__compute_T_and_N()
+    self.__verify()
+ 
+    if self.__trend:
+      if self.__poly > 1:
+        self.__df = self.detrend()
+        self.__trend = False
+
+    if self.__C and self.__trend:
+      self.__mode = 'ct'
+    elif self.__C:
+      self.__mode = 'c'
+    elif self.__trend:
+      raise TypeError('A Linear Trend cannot exist without a Constant.')
+    else:
+      self.__mode = 'n'
+
+  def __verify(self) -> None:
+    if self.__df.target.isnull().sum() > 0:
+      raise TypeError('Values in Target must NOT be NaN!')
+    if self.__poly < 1:
+      raise ValueError('The Polynomial Power Cannot be lesser than 1!')
+
+    for periods in self.__T:
+      if periods <= 6:
+        raise ValueError('The IPS tests expects longer Time Series (T > 6)')
+
+
+  def __compute_T_and_N(self) -> None:
+    self.__N = len(self.__df.SpUnit.unique())
+    self.__T = self.__df.groupby('SpUnit').size().values - self.__n_lags - 1
+
+  def detrend(self) -> pd.DataFrame:
+    lst = []
+    for unit in self.__df.SpUnit.unique():
+      subdf = self.__df[self.__df.SpUnit == unit].copy()
+      for i in range(1, self.__poly+1):
+        subdf.insert(3, f't^{i}',  np.linspace(1, len(subdf), len(subdf))**i)
+      diff = subdf['target'].copy() - sm.OLS(subdf['target'], sm.add_constant(subdf.iloc[:, 3:])).fit().predict(sm.add_constant(subdf.iloc[:, 3:]))
+      subdf.loc[:, 'target'] = diff
+      lst.append(subdf.iloc[:, :3])
+    return pd.concat(lst, axis=0)
+
+  def build_regressions(self, lags: int) -> list[pd.DataFrame]:
+    lst = []
+    for unit in self.__df.SpUnit.unique():
+      subdf = self.__df[self.__df.SpUnit == unit].copy()
+
+      subdf['target_1'] = subdf['target'].shift(1)
+      subdf['target_diff'] = subdf['target'] - subdf['target_1']
+
+      for i in range(1, lags + 1):
+        subdf[f'target_diff_{i}'] = subdf['target_diff'].shift(i)
+
+      if self.__trend:
+        subdf['t'] = np.arange(1, len(subdf) + 1)
+
+      if self.__trend:
+        base = ['target_diff', 't', 'target_1']
+      else:
+        base = ['target_diff', 'target_1']
+      additional = [f'target_diff_{i}' for i in range(1, lags + 1)]
+
+      subdf = subdf.loc[:, base + additional].iloc[lags + 1:, :]
+      lst.append(subdf)
+    return lst
+
+  def compute_per_panel_moments(self) -> dict:
+    means, variances = [], []
+    cache = {}
+    
+    for periods in self.__T:
+      
+      if periods not in cache:
+        result = compute_adf_moments(T=periods, mode = self.__mode, simulation_count=self.__n_reps, lag_depth=self.__n_lags, seed = self.__seed, chunksize = self.__chunksize, dask_scheduler=self.__scheduler)
+        means.append(result['E'])
+        variances.append(result['Var'])
+        cache[periods] = result
+      else:
+        means.append(cache[periods]['E'])
+        variances.append(cache[periods]['Var'])
+
+    return {'E_Mean': float(np.mean(means)), 'E_Var': float(np.mean(variances))}
+
+  def get_test_statistic(self) -> float:
+    moments = self.compute_per_panel_moments()
+    
+    regressions = self.build_regressions(self.__n_lags)
+    if self.__C:
+      t_bar = np.mean([sm.OLS(reg.loc[:, 'target_diff'], sm.add_constant(reg.drop(columns='target_diff'))).fit().tvalues['target_1'] for reg in regressions])
+    else:
+      t_bar = np.mean([sm.OLS(reg.loc[:, 'target_diff'], reg.drop(columns='target_diff')).fit().tvalues['target_1'] for reg in regressions])
+    
+    Z = np.sqrt(self.__N) * (t_bar - moments['E_Mean']) / np.sqrt(moments['E_Var'])
+    
+    return Z
+  
+  def verdict(self) -> None:
+    
+    Z_value = self.get_test_statistic()
+    p_value = sc.norm().cdf(Z_value)
+    
+    if p_value >= self.__alpha:
+      print(f"According to the IPS test, your variable is non-stationary I(1) with p-value >= alpha: {p_value} >= {self.__alpha} \n Lag amount: {self.__n_lags}")
+    else:
+      print(f"According to the IPS test, your variable is stationary I(0) with p-value < alpha: {p_value} < {self.__alpha} \n Lag amount: {self.__n_lags}")

econmethods-3.1.0.0/econmethods/__init__.py

@@ -0,0 +1,3 @@
+from .Lib import CIPS, Hausman, FECM, CDTest, SlopeHomogeneityF, IPS, compute_adf_moments
+
+__all__ = ['CIPS', 'Hausman', 'FECM', 'CDTest', 'SlopeHomogeneityF', 'IPS', 'compute_adf_moments']

{econmethods-3.0.6.2 → econmethods-3.1.0.0}/econmethods.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: econmethods
-Version: 3.0.6.2
+Version: 3.1.0.0
 Summary: A python package implementing various econometrical tests and estimators
 Home-page: https://github.com/NaturionBG/econmethods
 Author: NaturionBG
@@ -14,19 +14,12 @@ Requires-Dist: statsmodels>=0.14.5
 Requires-Dist: numpy>=2.3.5
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: scipy>=1.16.3
+Requires-Dist: dask>=2025.9.1
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
-Dynamic: description
 Dynamic: home-page
 Dynamic: license
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
-
-* econmethods
-
-A library made specifically for an econometrics project. 
-Contains implementations of various estimators and tests.
-
-The library is not made by a professional, hence, the implemented methods may require a very scecific data struture.

{econmethods-3.0.6.2 → econmethods-3.1.0.0}/econmethods.egg-info/requires.txt

@@ -2,3 +2,4 @@ statsmodels>=0.14.5
 numpy>=2.3.5
 pandas>=2.3.3
 scipy>=1.16.3
+dask>=2025.9.1

{econmethods-3.0.6.2 → econmethods-3.1.0.0}/setup.py

@@ -1,14 +1,11 @@
 from setuptools import find_packages, setup
 
-with open('README.md', 'r') as f:
-  long_desc = f.read()
-  
 setup(
   name = 'econmethods',
-  version = 'v3.0.6.2',
+  version = 'v3.1.0.0',
   description='A python package implementing various econometrical tests and estimators',
   packages = find_packages(),
-  long_description=long_desc,
+  long_description='',
   url = 'https://github.com/NaturionBG/econmethods',
   package_data= {
     "econmethods": ["CADF_Crit_Values.xlsx"]
@@ -26,6 +23,7 @@ setup(
     'statsmodels >= 0.14.5',
     'numpy >= 2.3.5',
     'pandas >= 2.3.3',
-    'scipy >= 1.16.3'
+    'scipy >= 1.16.3',
+    'dask >= 2025.9.1',
   ],
 )

econmethods-3.0.6.2/README.md

@@ -1,6 +0,0 @@
-* econmethods
-
-A library made specifically for an econometrics project. 
-Contains implementations of various estimators and tests.
-
-The library is not made by a professional, hence, the implemented methods may require a very scecific data struture.

econmethods-3.0.6.2/econmethods/__init__.py

@@ -1,3 +0,0 @@
-from .Lib import CipsTest, Hausman, FECM, CDTest, SlopeHomogeneityF
-
-__all__ = ['CipsTest', 'Hausman', 'FECM', 'CDTest', 'SlopeHomogeneityF']