Better documentation, renaming files, update README.md

Author: gusamarante

README.md

@@ -27,14 +27,28 @@ carries all the relevant variables as atributes:
 pip install pyacm
 ```
 
-# Example
-The tricky part is getting the correct data format. The model works with 
-annualized log-yields for zero-coupon bonds, observed at daily or monthly 
-frequency. Maturities must be equally spaced in monthly frequency and start 
-at month 1. This means that you need to construct a bootstraped curve for every
-date and interpolate it at fixed monthly maturities.
-
-MORE SOON...
+
+# Original Article
+> Adrian, Tobias and Crump, Richard K. and Moench, Emanuel, 
+> Pricing the Term Structure with Linear Regressions (April 11, 2013). 
+> FRB of New York Staff Report No. 340, 
+> Available at SSRN: https://ssrn.com/abstract=1362586 or http://dx.doi.org/10.2139/ssrn.1362586
+
+The version of the article that was published by the NY FED is not 100% explicit on how the data is being manipulated, 
+but I found an earlier version of the paper on SSRN where the authors go deeper into the details on how everything is being estimated:
+- Data for zero yields uses monthly maturities starting from month 1
+- All principal components and model parameters are estiamted with data resampled to a monthly frequency, averaging observations in each month
+- To get daily / real-time estimates, the factor loadings estimated from the monthly frquency are used to transform the daily data
+
+
+
+
+# Usage
+The tricky part of using this model is getting the correct data format:
+- The model works with annualized log-yields for zero-coupon bonds
+- Observations (index) must be in either monthly or daily frequency
+- Maturities (columns) must be equally spaced in **monthly** frequency and start at month 1. This means that you need to construct a bootstraped curve for every date and interpolate it at fixed monthly maturities.
+- Whichever maturity you want to be the longest, your input data should have one column more. For example, if you want term premium estimate up to the 10-year yield (120 months), your input data should include maturities up to 121 months. This is needed to properly compute the returns.
 
 
 # Observations

example.py renamed to example_br.py

@@ -8,7 +8,7 @@
 
 # Read and plot data
 yield_curve = pd.read_csv(
-    "sample_data/di monthly maturities.csv",
+    "sample_data/di monthly maturities.csv",  # TODO change to read from web
     index_col=0,
 )
 yield_curve = yield_curve.iloc[:, :121]  # maturities up to 10y

pyacm/__init__.py

@@ -1,3 +1,7 @@
 from pyacm.acm import NominalACM
+from pyacm.utils import FRED
 
-__all__ = ["NominalACM"]
+__all__ = [
+    "FRED",
+    "NominalACM",
+]

pyacm/acm.py

@@ -26,6 +26,88 @@ class NominalACM:
           month.
         - To get daily / real-time estimates, the factor loadings estimated
           from the monthly frquency are used to transform the daily data.
+
+    Attributes
+    ----------
+    n_factors: int
+        number of principal components used
+
+    curve: pandas.DataFrame
+        Raw data of the yield curve
+
+    curve_monthly: pandas.DataFrame
+        Yield curve data resampled to a monthly frequency by averageing
+        the observations
+
+    t: int
+        Number of observations in the timeseries dimension
+
+    n: int
+        Number of observations in the cross-sectional dimension. Same
+        as number of maturities available after returns are computed
+
+    rx_m: pd.DataFrame
+        Excess returns in monthly frquency
+
+    rf_m: pandas.Series
+        Risk-free rate in monthly frequency
+
+    rf_d: pandas.Series
+        Risk-free rate in daily frequency
+
+    pc_factors_m: pandas.DataFrame
+        Principal components in monthly frequency
+
+    pc_loadings_m: pandas.DataFrame
+        Factor loadings of the monthly PCs
+
+    pc_explained_m: pandas.Series
+        Percent of total variance explained by each monthly principal component
+
+    pc_factors_d: pandas.DataFrame
+        Principal components in daily frequency
+
+    pc_loadings_d: pandas.DataFrame
+        Factor loadings of the daily PCs
+
+    pc_explained_d: pandas.Series
+        Percent of total variance explained by each monthly principal component
+
+    mu, phi, Sigma, v: numpy.array
+        Estimates of the VAR(1) parameters, the first stage of estimation.
+        The names are the same as the original paper
+
+    a, beta, c, sigma2: numpy.array
+        Estimates of the risk premium equation, the second stage of estimation.
+        The names are the same as the original paper
+
+    lambda0, lambda1: numpy.array
+        Estimates of the price of risk parameters, the third stage of estimation.
+        The names are the same as the original paper
+
+    miy: pandas.DataFrame
+        Model implied / fitted yields
+
+    rny: pandas.DataFrame
+        Risk neutral yields
+
+    tp: pandas.DataFrame
+        Term premium estimates
+
+    er_loadings: pandas.DataFrame
+        Loadings of the expected reutrns on the principal components
+
+    er_hist_m: pandas.DataFrame
+        Historical estimates of expected returns, computed in-sample, in monthly frequency
+
+    er_hist_d: pandas.DataFrame
+        Historical estimates of expected returns, computed in-sample, in daily frequency
+
+    z_lambda: pandas.DataFrame
+        Z-stat for inference on the price of risk parameters
+
+    z_beta: pandas.DataFrame
+        Z-stat for inference on the loadings of expected returns
     """
 
     def __init__(self, curve, n_factors=5):