getfactormodels 0.0.1__py3-none-any.whl

getfactormodels/__init__.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+# MIT License
+#
+# Copyright (c) 2023 S. Martin
+#
+# 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.
+__version__ = "0.0.1"
+
+from .__main__ import FactorExtractor, get_factors
+from .models import models  # noqa: F401
+from .models.models import (barillas_shanken_factors, carhart_factors,
+                            dhs_factors, ff_factors, hml_devil_factors,
+                            icr_factors, liquidity_factors, mispricing_factors,
+                            q_classic_factors, q_factors)
+
+__all__ = ["FactorExtractor",
+           "ff_factors",
+           "icr_factors",
+           "q_factors",
+           "q_classic_factors",
+           "mispricing_factors",
+           "dhs_factors",
+           "liquidity_factors",
+           "hml_devil_factors",
+           "barillas_shanken_factors",
+           "carhart_factors",
+           "get_factors", ]

getfactormodels/__main__.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+# ruff: noqa: F401
+# TODO: rename __main__.py
+import os
+import pandas as pd
+from dateutil import parser
+from getfactormodels.models.models import barillas_shanken_factors  # noqa
+from getfactormodels.models.models import (carhart_factors, dhs_factors,
+                                           ff_factors, hml_devil_factors,
+                                           icr_factors, liquidity_factors,
+                                           mispricing_factors,
+                                           q_classic_factors, q_factors)
+from getfactormodels.utils.cli import parse_args
+from getfactormodels.utils.utils import _get_model_key, _process
+
+
+def get_factors(model: str = "3",  # noqa: C901
+                frequency: str = "M",
+                start_date=None,
+                end_date=None,
+                output=None) -> pd.DataFrame:
+    """Get data for a specified factor model.
+
+    Return a DataFrame containing the data for the specified model and
+    frequency. If an output is specified, factor data is saved to a file.
+
+    Notes:
+    - Any string matching a model's regex (e.g., `liq` for `liquidity`) can be 
+      used as a model name.
+    - Dates should be in ``YYYY-MM-DD`` format, but anything that 
+      ``dateutil.parser.parse()`` can interpret will work.
+    - Weekly data is only available for the q-factor and Fama-French 3-factor
+      models.
+
+    Parameters:
+        model (str): the factor model to return. One of: `liquidity`,
+            `icr`, `dhs`, `q`, `q_classic`, `ff3`, `ff5`, `ff6`, `carhart4`, 
+            `hml_devil`, `barrilas_shanken`, or `mispricing`.
+        frequency (str): the frequency of the data. D, W, M or A (default: M).
+        start_date (str, optional): the start date of the data, YYYY-MM-DD.
+        end_date (str, optional): the end date of the data, YYYY-MM-DD.
+        output (str, optional): a filename, directory, or filepath. Accepts
+            '.txt', '.csv', '.md', '.xlsx', '.pkl' as file extensions.
+
+    Returns:
+        pandas.DataFrame: factor data, indexed by date.
+    """
+    frequency = frequency.lower()
+    model = _get_model_key(model)
+
+    # Get the function by its name, if it exists call it with params
+    if model in ["3", "4", "5", "6"]:
+        return ff_factors(model, frequency, start_date, end_date)
+    else:
+        function_name = f"{model}_factors"
+        function = globals().get(function_name)
+
+    if not function:
+        raise ValueError(f"Invalid model: {model}")
+
+    df = function(frequency, start_date, end_date, output)
+    return df
+
+
+class FactorExtractor:
+    """
+    Extracts factor data based on specified parameters.
+
+    Args:
+        model : str
+            The factor model to use. Defaults to '3'.
+        frequency (str, optional): The frequency of the data. Defaults to 'M'.
+        start_date (str, optional): The start date of the data.
+        end_date (str, optional): The end date of the data.
+
+    Methods:
+        drop_rf: Drops the 'RF' column from the DataFrame.
+        save_factors: Saves the factor data to a file.
+    """
+
+    def __init__(self,
+                 model='3',
+                 frequency='M',
+                 start_date=None,
+                 end_date=None,
+                 output=None):
+        self.model: str = model
+        self.frequency: str = frequency
+        self.start_date = self.validate_date_format(start_date) if start_date \
+            else None
+        self.end_date = self.validate_date_format(end_date) if end_date \
+            else None
+        self.output = output
+        self._no_rf = False
+        self.df = None
+
+    def no_rf(self):
+        """Sets the _no_rf flag to True."""
+        self._no_rf = True
+
+    @staticmethod
+    def validate_date_format(date_string):
+        """
+        Validate the date format.
+
+        Raises:
+            ValueError: If the date format is incorrect.
+        """
+        try:
+            return parser.parse(date_string).strftime("%Y-%m-%d")
+        except ValueError as err:
+            raise ValueError("Incorrect date format, use YYYY-MM-DD.") from err
+
+    def get_factors(self) -> pd.DataFrame:
+        """Fetch the factor data and store it in the class."""
+        self.df = get_factors(
+            model=self.model,
+            frequency=self.frequency,
+            start_date=self.start_date,
+            end_date=self.end_date)
+
+        if self._no_rf:
+            self.df = self.drop_rf(self.df)
+
+        return self.df
+
+    def drop_rf(self, df):
+        """Drop the ``RF`` column from the DataFrame."""
+        if "RF" in df.columns:
+            df = df.drop(columns=["RF"])
+        else:
+            print("`drop_rf` was called but no RF column was found.")
+
+        return df
+
+    def to_file(self, filename):
+        """
+        Save the factor data to a file.
+
+        Args:
+            filename (str): The name of the file to save the data to.
+        """
+        if self.df is None:
+            raise ValueError("No data to save. Fetch factors first.")
+
+        # TODO: could call _save_to_file directly
+        _process(self.df, filepath=filename)
+
+
+def main():
+    args = parse_args()
+
+    extractor = FactorExtractor(model=args.model, frequency=args.freq,
+                                start_date=args.start, end_date=args.end)
+    if args.no_rf:
+        extractor.no_rf()
+
+    df = extractor.get_factors()
+
+    if args.output:
+        extractor.to_file(args.output)
+        print(f'File saved to "{os.path.abspath(args.output)}"')
+    else:
+        print(df)
+
+
+if __name__ == '__main__':
+    main()

getfactormodels/models/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+# MIT License
+#
+# Copyright (c) 2023 S. Martin
+#
+# 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.
+from . import ff_models  # noqa: F401 - TODO: disable 401 in all __init__
+from . import models  # noqa: F401

getfactormodels/models/ff_models.py

@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+import numpy as np
+import pandas as pd  # noqa: D100
+from ..utils.utils import (  # noqa - todo: fix relative import from parent modules banned
+    _process, get_zip_from_url)
+
+
+def _ff_construct_url(model="3", frequency="M"):
+    """Construct and return the URL for the specified model and frequency."""
+    frequency = frequency.upper()
+
+    if frequency == "W" and model not in ["3", "4"]:  # why 4?
+        raise ValueError("Weekly data is only available for the Fama \
+                         French 3 factor model at the moment.")
+
+    base_url = "https://mba.tuck.dartmouth.edu"
+    ftp = "pages/faculty/ken.french/ftp"
+
+    file = f'F-F_{"Research_Data_" if model in ["3", "4", "5", "6"] else ""}'
+    file += ("Factors" if model in ["3", "4"]
+             else "5_Factors_2x3" if model in ["5", "6"]
+             else "")
+    file += "_daily" if frequency == "D" \
+        else "_weekly" if frequency == "W" else ""
+    file += "_CSV.zip"
+
+    return f"{base_url}/{ftp}/{file}"
+
+
+def ff_read_csv_from_zip(zip_file, model=None):
+    """Read the FF Factors CSV into a dataframe."""
+    try:
+        filename = zip_file.namelist()[0]
+        with zip_file.open(filename) as file:
+            data = pd.read_csv(
+                file,
+                skiprows=12 if 'momentum' in filename.lower() else 3 if 'ly' in filename.lower() else 2,  # noqa: E501
+                index_col=0,
+                header=0,
+                parse_dates=False,
+                skipfooter=1,
+                engine="python")
+
+            data.index = data.index.astype(str)
+            data.index = data.index.str.strip()
+            data.index.name = "date"
+            data = data.dropna()
+    except Exception as e:
+        print(f"Error reading file: {e}")
+        return None
+    return data
+
+
+def ff_process_data(data, model, frequency) -> pd.DataFrame:
+    """Process and return the data based on the provided model and frequency.
+    """
+    frequency = frequency.lower()
+
+    if frequency == 'm':
+        data = data[data.index.str.len() == 6]
+    elif frequency == 'y':
+        data = data[data.index.str.len() == 4]
+    else:
+        data = data[data.index.str.len() == 8]
+
+    try:
+        if frequency == 'm':
+            data.index = pd.to_datetime(data.index, format='%Y%m') \
+                + pd.offsets.MonthEnd(0)
+        else:
+            data.index = pd.to_datetime(data.index, format='%Y%m%d')
+
+    except Exception:
+        data.index = pd.to_datetime(data.index, format='%Y') \
+            + pd.offsets.YearEnd(0, month=12)
+
+    data.index.name = "date"
+
+    # All values (eg, 4/D, are <5% distinct).
+    # If <10% distinct, categorize
+    # if len(data) / data.nunique() < 10:
+    #     data = data.astype('category')
+
+    return data
+
+
+def _ff_get_mom(frequency) -> pd.Series:
+    """Fetch and return the momentum factor data as a pd.Series.
+        * Note: only for returning the raw data for the 4 and 6 factor models.
+    """
+    frequency = frequency.upper()
+    base_url = "https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/ftp"
+    file = "F-F_Momentum_Factor_daily_CSV.zip" if frequency == "D" \
+        else "F-F_Momentum_Factor_CSV.zip"
+    url = f"{base_url}/{file}"
+
+    csv = ff_read_csv_from_zip(get_zip_from_url(url))
+
+    csv.columns = ["MOM"]
+    csv.index.name = "date"
+
+    csv.index = csv.index.astype(str)
+    csv.index = csv.index.str.strip()
+
+    return csv
+
+
+def _get_ff_factors(model: str = "3",
+                    frequency: str = "M",
+                    start_date=None,
+                    end_date=None) -> pd.DataFrame:
+    """Return the Fama French 3, 5, or 6, or Carhart 4 factor model data.
+
+        * Note: This is the function that's called by get_ff_factors in main.
+    """
+    if frequency is None:
+        frequency = "M"
+    url = _ff_construct_url(model, frequency)
+    zip = get_zip_from_url(url)
+    csv = ff_read_csv_from_zip(zip, model)
+
+    if model in ["4", "6"]:
+        mom = _ff_get_mom(frequency)
+        if model == "6":
+            mom = mom.rename(columns={"MOM": "UMD"})
+        mom = pd.DataFrame(mom)
+        csv = csv.join(mom, how="left")
+
+    data = ff_process_data(csv, model, frequency)
+    data = data.apply(pd.to_numeric, errors='ignore')
+
+    if start_date is not None or end_date is not None:
+        data = data.loc[start_date:end_date]
+
+    data = data.dropna()
+
+    data = np.multiply(data, 0.01)
+    return _process(data, start_date, end_date)
+
+
+# TODO: just redo all of this.

getfactormodels/models/models.py

@@ -0,0 +1,462 @@
+# -*- coding: utf-8 -*-
+"""
+models
+=======
+Functions for retrieving and processing multi-factor model data.
+
+Functions for fetching data for a variety of factor models. The data can be
+returned for different frequencies and for a specified date range. The function
+supports a variety of model names that match specific regex patterns, including
+'liquidity', 'icr', 'dhs', 'q', 'q_classic', 'ff3', 'ff5', 'ff6', 'carhart4',
+'hml_devil', 'barrilas_shanken', and 'mispricing'.
+
+Functions
+---------
+- `ff_factors`: Retrieves data for a specified Fama-French or Carhart factor
+    model.
+- `q_factors`: Retrieves the q-factor model data from global-q.org.
+- `q_classic_factors`: Retrieves the original 4-factor "q" model of Hou, Xue,
+    and Zhang (2015).
+- `dhs_factor`: Retrieves the Daniel-Hirshleifer-Sun Behavioural factors.
+- `icr_factors`: Retrieves the He, Kelly, Manela (2017) ICR factors.
+- `hml_devil_factors`: Retrieves the HML Devil factors from AQR.
+- `barillas_shanken_factors`: Constructs the 6-factor model of Barillas and
+    Shanken.
+- `carhart_factors`: Retrieves the Carhart 4-factor model data.
+- `liquidity_factors`: Retrieves the Pastor-Stambaugh liquidity factors.
+- `mispricing_factors`: Retrieves the Stambaugh-Yuan (201x) mispricing factors.
+"""
+import os
+import pickle
+from io import BytesIO
+from typing import Optional, Union
+import numpy as np
+import pandas as pd
+import requests
+from getfactormodels.utils.utils import _process, get_file_from_url
+from .ff_models import _get_ff_factors
+
+
+def ff_factors(model: str = "3",  # TODO: fix: _get_ff_factors filepath param
+               frequency: str = "M",
+               start_date: str = None,
+               end_date: str = None,
+               output: str = None) -> pd.DataFrame:
+    """Get data for a specified Fama-French or Carhart factor model.
+
+    This function returns a DataFrame containing the 3-factor (1993), 5-factor
+    (2015), or 6-factor (2018) model of Fama & French, or Carhart's (1997)
+    4-factor model. Data is available in daily, weekly, monthly, and annual
+    frequencies. If an output is specified, saves the data to a file.
+
+    Notes:
+    - Only the 3-factor model offers weekly data.
+    - Dates should be in ``YYYY-MM-DD`` format, but anything that
+      ``dateutil.parser.parse()`` can interpret will work.
+
+    Parameters:
+        model (str, int): the Fama-French or Carhart factor data to return. 3, 4, 5
+            or 6 (default: 3).
+        frequency (str): the frequency of the data. Accepts D, W, M or Y
+            (default: M).
+        start_date (str, optional): the start date of the data, as YYYY-MM-DD.
+        end_date (str, optional): the end date of the data, as YYYY-MM-DD.
+        output (str, optional): a filename, directory, or filepath. If no
+            extension is provided, will output a '.csv'. Accepts '.txt',
+            '.csv', '.md', '.xlsx', '.pkl'.
+
+    Returns:
+        pandas.DataFrame: factor data, indexed by date.
+    """
+    model = str(model)
+    data = _get_ff_factors(model, frequency, start_date, end_date)
+    return _process(data, start_date, end_date, filepath=output)
+
+
+def liquidity_factors(frequency: str = "M",
+                      start_date: str = None,
+                      end_date: str = None,
+                      output: str = None) -> pd.DataFrame:
+    """Retrieve the Pastor-Stambaugh liquidity factors. Monthly data only."""
+    url = 'https://research.chicagobooth.edu/'
+    url += '-/media/research/famamiller/data/liq_data_1962_2022.txt'
+
+    if frequency.lower() != 'm':
+        print('Liquidity factors are only available for monthly frequency.')
+        raise ValueError("Frequency must be 'm'.")
+
+    # Get .csv here...
+    data = get_file_from_url(url)
+
+    # Headers are last commented line
+    headers = [line[1:].strip().split('\t')
+               for line in data.readlines() if line.startswith('%')][-1]
+
+    # Fix: was losing first line of data
+    data.seek(0)
+
+    # ...read .csv here
+    data = pd.read_csv(data, sep='\\s+', names=headers,
+                       comment='%', index_col=0)
+
+    data.index.name = 'date'
+    data.index = data.index.astype(str)
+
+    data = data.rename(columns={'Agg Liq.': 'AGG_LIQ',
+                                'Innov Liq (eq8)': 'INNOV_LIQ',
+                                'Traded Liq (LIQ_V)': 'TRADED_LIQ'})
+
+    # The first 65 values in the traded liquidity series are -99.000000.
+    data['TRADED_LIQ'] = data['TRADED_LIQ'].replace(-99.000000, 0)
+
+    if frequency.lower() == 'm':
+        data.index = pd.to_datetime(data.index, format='%Y%m') \
+            + pd.offsets.MonthEnd(0)
+
+    return _process(data, start_date, end_date, filepath=output)
+
+
+def mispricing_factors(frequency: str = "M",
+                       start_date: str = None,
+                       end_date: str = None,
+                       output: str = None) -> pd.DataFrame:
+    """Retrieve the Stambaugh-Yuan mispricing factors. Daily and monthly."""
+    if frequency.lower() not in ["d", "m"]:
+        print("Mispricing factors are only available for daily and monthly \
+            frequency.")
+        raise ValueError("Frequency must be 'd' or 'm'.")
+        return None
+
+    file = "M4d" if frequency == "d" else "M4"
+    url = f"https://finance.wharton.upenn.edu/~stambaug/{file}.csv"
+
+    data = get_file_from_url(url)
+
+    data = pd.read_csv(data, index_col=0, parse_dates=False,
+                       date_format="%Y%m%d", engine="pyarrow")  # only model
+                                                                # using pyarrow?  # noqa
+
+    data = data.rename(columns={"SMB": "SMB_SY",
+                                "MKTRF": "Mkt-RF"}).rename_axis("date")
+
+    if frequency == "d":
+        data.index = pd.to_datetime(data.index, format="%Y%m%d")
+    elif frequency == "m":
+        data.index = pd.to_datetime(data.index, format="%Y%m")
+        data.index = data.index + pd.offsets.MonthEnd(0)
+
+    return _process(data, start_date, end_date, filepath=output)
+
+
+def q_factors(frequency: str = "M",
+              start_date: str = None,
+              end_date: str = None,
+              output: str = None,
+              classic: bool = False) -> pd.DataFrame:
+    """Retrieve the q-factor model data."""
+    frequency = frequency.upper()
+    file = {"M": "monthly",
+            "D": "daily",
+            "Q": "quarterly",
+            "W": "weekly",
+            "Y": "annual", }.get(frequency)
+
+    base_url = 'https://global-q.org/uploads'
+    url = f"{base_url}/1/2/2/6/122679606/q5_factors_{file}_2022.csv"
+
+    index_cols = [0, 1] if frequency in ["M", "Q"] else [0]
+    data = pd.read_csv(
+        url, parse_dates=False, index_col=index_cols, float_precision="high")
+
+    if classic:
+        data = data.drop(columns=["R_EG"])
+
+    data = data.rename(columns={"R_F": "RF"})
+
+    data = np.multiply(data, 0.01)
+
+    if frequency in ["M", "Q"]:
+        # Need to insert "-" (monthly) or "Q" (quarterly) into date str.
+        data = data.reset_index()
+        col = "quarter" if frequency == "Q" else "month"
+        char = "Q" if frequency == "Q" else "-"
+
+        data["date"] = pd.PeriodIndex(
+            data["year"].astype(str)
+            + char
+            + data[col].astype(str), freq=frequency
+        ).to_timestamp(how="end")
+
+        data["date"] = data["date"].dt.normalize()
+        data = data.drop(["year", col], axis=1).set_index("date")
+
+    if frequency == "Y":
+        data.index = pd.to_datetime(data.index.astype(str)) \
+            + pd.offsets.YearEnd(0)
+    else:
+        data.index = pd.to_datetime(data.index.astype(str))
+
+    data.columns = data.columns.str.upper()
+    data.index.name = "date"
+    data = data.rename(columns={"R_MKT": "Mkt-RF"})
+
+    return _process(data, start_date, end_date, filepath=output)
+
+
+# Daniel-Hirshleifer-Sun Behavioural Factors
+def dhs_factors(frequency: str = "M",
+                start_date: str = None,
+                end_date: str = None,
+                output: str = None) -> pd.DataFrame:
+    """Retrieve DHS factors from sheets on Lin Sun's website."""
+    frequency = frequency.lower()
+    base_url = "https://docs.google.com/spreadsheets/d/"
+
+    if frequency.lower() == "m":
+        file = "1RxYLbCfk19m8fnniiJYfaj3yI55ZPaoi/export?format=xlsx"
+    elif frequency.lower() == "d":
+        file = "1KnCP-NVhf2Sni8bVFIVyMxW-vIljBOWE/export?format=xlsx"
+    else:
+        print("Frequency must be either 'M' (monthly) or 'D' (daily).")
+        raise ValueError("Frequency must be 'M' or 'D'.")
+    # TODO: use the link to the Google Sheet instead of the actual sheet.
+
+    url = base_url + file
+
+    response = requests.get(url, verify=True, timeout=20)
+    file = BytesIO(response.content)
+
+    data = pd.read_excel(file, index_col="Date",
+                         usecols=['Date', 'FIN', 'PEAD'], engine='openpyxl',
+                         header=0, parse_dates=False)
+    data.index.name = "date"
+
+    if frequency.lower() == "d":
+        data.index = pd.to_datetime(data.index, format="%m/%d/%Y")
+    else:
+        data.index = pd.to_datetime(data.index, format="%Y%m")
+        data.index = data.index + pd.offsets.MonthEnd(0)
+
+    data = np.multiply(data, 0.01)  # Decimalize before FF factors!
+
+    ff = _get_ff_factors(model="3", frequency=frequency,
+                         start_date=data.index[0], end_date=data.index[-1])
+    ff = ff.round(4)
+    # Note: FF source data is to 4 decimals; re-rounding here to avoid
+    #       rounding errors (e.g., 0.02 --> 0.019999999999999997)
+    data = pd.concat([ff["Mkt-RF"], data, ff["RF"]], axis=1)
+    data.index.name = "date"
+
+    return _process(data, start_date, end_date, filepath=output)
+
+
+def icr_factors(frequency: str = "M",
+                start_date: str = None,
+                end_date: str = None,
+                output: str = None) -> pd.DataFrame:
+    """Retrieve the He, Kelly, Manela (2017) ICR factors.
+    * Daily since 1999-05-03; quarterly and monthly since 1970.
+    """
+    # TODO: Do we need Mkt-RF and RF [seen reffered to as 2-factor model]?
+    frequency = frequency.lower()
+
+    if frequency not in ["d", "m", "q"]:
+        raise ValueError("Frequency must be 'd', 'm' or 'q'.")
+
+    base_url = "https://voices.uchicago.edu/zhiguohe"
+    file = {"d": "daily", "m": "monthly", "q": "quarterly"}.get(frequency)
+    url = f"{base_url}/files/2023/10/He_Kelly_Manela_Factors_{file}.csv"
+
+    df = get_file_from_url(url)
+    df = pd.read_csv(df)
+    df = df.rename(columns={df.columns[0]: "date"})
+
+    # Just doing dates here for now...
+    if frequency == "q":
+        # The dates are YYYYQ. [19752 -> 1975Q2]
+        df["date"] = df["date"].astype(str)
+        df["date"] = df["date"].str[:-1] + "Q" + df["date"].str[-1]
+        df["date"] = pd.PeriodIndex(df["date"], freq="Q").to_timestamp() \
+            + pd.offsets.QuarterEnd(0)
+
+    df = df.rename(columns={
+            "intermediary_capital_ratio": "IC_RATIO",
+            "intermediary_capital_risk_factor": "IC_RISK_FACTOR",
+            "intermediary_leverage_ratio_squared": "INT_LEV_RATIO_SQ",
+            "intermediary_value_weighted_investment_return": "INT_VW_ROI", })
+
+    if frequency == "m":
+        df["date"] = pd.to_datetime(df["date"], format="%Y%m")
+        df["date"] = df["date"] + pd.offsets.MonthEnd(0)
+
+    elif frequency == "d":
+        df["date"] = pd.to_datetime(df["date"], format="%Y%m%d")
+
+    df = df.set_index("date")
+
+    return _process(df, start_date, end_date, filepath=output)
+
+
+def q_classic_factors(frequency: str = "M",
+                      start_date: str = None,
+                      end_date: str = None,
+                      output: str = None) -> pd.DataFrame:
+    """Retrieve the classic q-factor model of Hou, Xue, and Zhang (2015)."""
+    return q_factors(frequency, start_date, end_date, output=output,
+                     classic=True)
+
+
+def carhart_factors(frequency: str = "M",
+                    start_date: str = None,
+                    end_date: str = None,
+                    output: str = None) -> pd.DataFrame:
+    """Retrieve the Carhart 4-factor model data."""
+    data = _get_ff_factors(model='4', frequency=frequency,
+                           start_date=start_date,
+                           end_date=end_date)
+    return _process(data, start_date, end_date, filepath=output)
+
+
+def _create_cache():
+    cache_dir = os.path.expanduser('~/.cache/getfactormodels')
+    if not os.path.exists(cache_dir):
+        os.makedirs(cache_dir)
+
+
+def hml_devil_factors(frequency='M',
+                      start_date: Optional[str] = None,
+                      end_date: Optional[str] = None,
+                      output: Optional[str] = None,
+                      series=False) -> Union[pd.Series, pd.DataFrame]:
+    """***EXPERIMENTAL***
+
+    Retrieve the HML Devil factors from AQR.com. [FIXME: Slow.]
+
+    Notes:
+    - Slow. Very slow. So we implement a cache and it doesn't need to run
+    again until tomorrow (daily) or next month.
+
+    Parameters:
+        frequency (str): The frequency of the data. M, D (default: M)
+        start_date (str, optional): The start date of the data, YYYY-MM-DD.
+        end_date (str, optional): The end date of the data, YYYY-MM-DD.
+        output (str, optional): The filepath to save the output data.
+        series (bool, optional): If True, return the HML Devil factors as a
+            pandas Series.
+
+    Returns:
+        pd.DataFrame: the HML Devil model data indexed by date.
+        pd.Series: the HML factor as a pd.Series
+    """
+    _create_cache()  # TODO: allow config and cache_file [not pickle]
+    pickle_file = os.path.expanduser(f'~/.cache/getfactormodels/hml_devil_{frequency}.pkl')  # noqa
+
+    # Get the current date and the date of the file creation
+    current_date = pd.to_datetime('today')
+    if os.path.exists(pickle_file):
+        file_date = pd.to_datetime(os.path.getmtime(pickle_file), unit='s')
+
+        # If the pickle file exists and is not expired, load the df from it
+        if (frequency.lower() == 'd' and file_date.day == current_date.day) or \
+                (frequency.lower() != 'd' and file_date.month == current_date.month):  # noqa
+            with open(pickle_file, 'rb') as f:
+                if series:
+                    return _process(pickle.load(f),  # read pickle instead, csv ?  # noqa
+                                    start_date, end_date).HML_DEVIL
+                else:
+                    data = _process(pickle.load(f), start_date, end_date)
+                    data = data.dropna()
+                    return data
+        # If the pickle file is expired, delete it
+        else:
+            os.remove(pickle_file)
+
+    base_url = 'https://www.aqr.com/-/media/AQR/Documents/Insights/'
+    file = 'daily' if frequency.lower() == 'd' else 'monthly'
+    url = f'{base_url}/Data-Sets/The-Devil-in-HMLs-Details-Factors-{file}.xlsx'
+
+    print('Downloading HML Devil factors from AQR... This can take a while. Please be patient or something.')  # noqa
+
+    # TODO: A progress bar until something's figured out? download_with_progress  # noqa
+    # TODO: Handle interupts SIGINT, etc.
+    response = requests.get(url, verify=True, timeout=180)
+    xls = pd.ExcelFile(BytesIO(response.content))
+
+    sheets = {0: 'HML Devil', 4: 'MKT', 5: 'SMB', 7: 'UMD', 8: 'RF'}
+    dfs = []
+
+    df_dict = pd.read_excel(xls,
+                            sheet_name=list(sheets.values()),
+                            skiprows=18,
+                            header=0,
+                            index_col=0,
+                            parse_dates=True)
+
+    for sheet_index, sheet_name in sheets.items():
+        df = df_dict[sheet_name]
+
+        # Use 'USA' col, except for the RF sheet, use cols first two cols
+        df = df[['USA']] if sheet_index != 8 else df.iloc[:, 0:1]
+        # TODO: allow for other countries
+
+        df.columns = [sheet_name]
+        dfs.append(df)
+
+    data = pd.concat(dfs, axis=1)
+    data.rename(columns={'MKT': 'Mkt-RF',
+                         'HML Devil': 'HML_DEVIL'}, inplace=True)
+    data = data.astype(float)
+
+    with open(pickle_file, 'wb') as f:
+        pickle.dump(data, f)
+
+    if os.path.exists('hml_devil.csv'):
+        os.remove('hml_devil.csv')
+
+    data.index.name = 'date'
+
+    data.index = pd.to_datetime(data.index)
+
+    if frequency.lower() == 'd':
+        data = data.dropna()
+
+    if series:
+        return _process(data, start_date, end_date, filepath=output).HML_DEVIL
+
+    return _process(data, start_date, end_date, filepath=output)
+
+
+def barillas_shanken_factors(frequency: str = 'M',
+                             start_date: str = None,
+                             end_date: str = None,
+                             output: str = None) -> pd.DataFrame:
+    """***Experimental.***
+
+    Constructs the 6-factor model of Barillas and Shanken.  It's a
+    combination of the 5-factor model of Fama and French (2015), the q-factor
+    model of Hou, Xue, and Zhang (2015), and Asness and Frazzini's HML Devil.
+    This is the factor model with the highest posterior inclusion probability
+    in Barillas and Shanken (2018).
+
+    Note:
+        - Relies on the HML Devil factors being retrieved (which is very slow).
+
+    Returns:
+        pd.DataFrame: A timeseries of the factor data.
+    """
+    q = q_factors(frequency=frequency, classic=True)[['R_IA', 'R_ROE']]
+    ff = ff_factors(model='6', frequency=frequency)[['Mkt-RF', 'SMB', 'UMD',
+                                                     'RF']]
+
+    df = pd.merge(q, ff, left_index=True, right_index=True, how='inner')
+
+    hml_devil = hml_devil_factors(frequency=frequency, start_date=start_date,
+                                  series=True)
+
+    hml_devil = hml_devil.rename('HML_m')
+    hml_devil.index.name = 'date'
+
+    df = pd.merge(df, hml_devil, left_index=True,
+                  right_index=True, how='inner')
+
+    return _process(df, start_date, end_date, filepath=output)

getfactormodels/utils/cli.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+import argparse
+
+
+def parse_args():
+    """Argument parser, allowing for command line arguments.
+    This is the function used in pyproject.toml to run the CLI."""
+    parser = argparse.ArgumentParser(
+        description='Retrieve and structure data for factor models.',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''Example usage:
+        python main.py -m 3 -f M -s 1961-01-01 -e 1990-12-31
+        python main.py --model icr --frequency M --end 1990-12-31 --no_rf -o '~/icr.csv' '''  # noqa
+    )
+    parser.add_argument('-m', '--model', type=str, required=True,
+                        help='The model to use.')
+    parser.add_argument('-f', '--freq', '--frequency', type=str,
+                        required=False, default='M', help='The frequency of\
+                        the data. Valid options are D, W, M, Q, A.')
+    parser.add_argument('-s', '--start', type=str, required=False,
+                        help='The start date for the data.')
+    parser.add_argument('-e', '--end', type=str, required=False,
+                        help='The end date for the data.')
+    parser.add_argument('-o', '--output', type=str, required=False,  # noqa
+                        help='The file to save the data to.')
+    parser.add_argument('--no_rf', '--no-rf', '--norf', action='store_true',
+                        help='Drop the RF column from the DataFrame.')
+    return parser.parse_args()

getfactormodels/utils/utils.py

@@ -0,0 +1,174 @@
+# -*- coding: utf-8 -*-
+import re
+import zipfile as zip
+from datetime import datetime
+from io import BytesIO, StringIO
+from pathlib import Path
+from types import MappingProxyType
+import pandas as pd
+import requests
+from dateutil import parser
+
+__model_input_map = MappingProxyType({
+    "3": r"\b((f?)f)?3\b|(ff)?1993",
+    "5": r"\b(ff)?5|ff2015\b",
+    "4": r"\b(c(ar(hart)?)?4?|ff4|carhart1997|4)\b",
+    "6": r"\b(ff)?6|ff2018\b",
+    "q": r"\b(q(5)?|hmxz)\b",
+    "q_classic": r"\b(q4|q(_)?classic)|classic_q\b",
+    "mispricing": r"\b(sy4?|mispricing)|misp|yuan$|m4|mis|sy\b",
+    "liquidity": r"^(il)?liq(uidity)?|(pastor|ps|sp)$",
+    "icr": r"\bicr|hkm\b",
+    "dhs": r"^(\bdhs\b|behav.*)$",
+    "hml_devil": r"\bhml(_)?d(evil)?\b",
+    "barillas_shanken": r"\b(bs|bs6|barillas|shanken)\b", })
+
+
+def _get_model_key(model):
+    """
+    Convert a model name to a model key.
+    * This provides more flexibility in input by converting various model names
+    to a standardized model key.
+
+    >>> _get_model_key('ff1993')
+    '3'
+    >>> _get_model_key('liQ')
+    'liquidity'
+    >>>  _get_model_key('q4_factors')
+    'q_classic'
+    >>> _get_model_key('ICR')
+    'icr'
+    """
+    model = str(model)
+
+    for key, regex in __model_input_map.items():
+        if re.match(regex, model, re.I):
+            return key
+    raise ValueError(f'Invalid model: {model}')
+
+
+def get_file_from_url(url):
+    """Get a file from a URL and return its content as a StringIO object."""
+    response = requests.get(url, verify=True, timeout=15)
+    response.raise_for_status()
+    response_content = response.content.decode('utf-8')
+    content = StringIO(response_content)
+    return content
+
+
+def get_zip_from_url(url):
+    """Download a zip file from a URL and return a ZipFile object."""
+    try:
+        response = requests.get(url, timeout=15)
+        response.raise_for_status()
+        content = response.content
+    except (KeyboardInterrupt, Exception) as e:
+        print(f"An error occurred downloading the zip file from {url}: {e}")
+        raise
+
+    return zip.ZipFile(BytesIO(content))
+
+
+def _save_to_file(data, filename=None, output_dir=None):
+    """Save a pandas dataFrame to a file."""
+    if isinstance(data, (pd.DataFrame, pd.Series)):
+        formats = {
+            '.txt': lambda filename: data.to_csv(filename, sep='\t'),
+            '.csv': data.to_csv,
+            '.xlsx': data.to_excel,  # TODO: style with writer
+            '.pkl': data.to_pickle,
+            '.md': data.to_markdown, }
+
+        if filename is None:
+            filename = datetime.now().strftime('%Y-%m-%d') + '.csv'
+        elif '.' not in filename:
+            filename += '.csv'
+
+            # If no output directory is provided, use the current working
+            # directory
+        if output_dir is None:
+            output_dir = Path.cwd()
+        else:
+            # Expand the '~' character in the output directory
+            output_dir = Path(output_dir).expanduser()
+
+        # Create the full file path
+        filename = output_dir / filename
+
+        # Check if file exists
+        if filename.is_file():
+            print('File exists: overwriting...')
+
+        for ext, func in formats.items():
+            if str(filename).endswith(ext):
+                func(str(filename))
+                print(f"File saved to: {filename}")
+                break
+
+        else:
+            raise ValueError('Unsupported file extension')
+    else:
+        raise ValueError('Data is not a pandas DataFrame or Series')
+
+
+def _rearrange_cols(data):
+    """Rearrange the columns of the dataframe.
+    * NOTE: this is faster:
+            cols = data.columns.values
+            cols_order = np.concatenate(([np.where(cols == 'Mkt-RF')[0], \
+                np.where((cols != 'Mkt-RF') & (cols != 'RF'))[0], \
+                    np.where(cols == 'RF')[0]]))
+            return data.iloc[:, cols_order]
+    """
+    # [TODO] ICR model has no RF or Mkt Excess return column
+    if isinstance(data, pd.Series):
+        return data
+    cols = list(data.columns)
+    if 'Mkt-RF' in cols:
+        cols.insert(0, cols.pop(cols.index('Mkt-RF')))
+    if 'RF' in cols:
+        cols.append(cols.pop(cols.index('RF')))
+    return data.loc[:, cols]
+
+
+def _validate_date(date_str):
+    """Use `dateutil.parser.parse` to validate a date format."""
+    if date_str is None:
+        return None
+    if isinstance(date_str, pd.Timestamp):
+        return date_str.strftime("%Y-%m-%d")
+    try:
+        return parser.parse(date_str).strftime("%Y-%m-%d")
+    except ValueError as err:
+        raise ValueError("Incorrect date format, use YYYY-MM-DD.") from err
+
+
+def _slice_dates(data, start_date=None, end_date=None):
+    """Slice the dataframe to the specified date range."""
+    if start_date is None and end_date is None:
+        return data
+
+    if start_date is not None:
+        start_date = _validate_date(start_date)
+    if end_date is not None:
+        end_date = _validate_date(end_date)
+
+    return data.loc[slice(start_date, end_date)]
+
+
+def _process(data, start_date=None, end_date=None, filepath=None):
+    """Process the data and optionally save it to a file.
+        * filepath: takes a filename, path or directory.
+    """
+    data = _rearrange_cols(data)
+    data = _slice_dates(data, start_date, end_date)
+
+    if filepath:
+        # Convert the filepath to a Path object and expand the '~' character
+        filepath = Path(filepath).expanduser()
+
+        dir_path, filename = filepath.parent, filepath.name
+
+        _save_to_file(data, filename, dir_path)
+
+    return data

getfactormodels-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 S. Martin
+
+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.

getfactormodels-0.0.1.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.1
+Name: getfactormodels
+Version: 0.0.1
+Summary: Retreive data for various multifactor asset pricing models.
+Keywords: finance,pricing models,financial analysis,econometrics,asset pricing,multifactor models
+Author-email: "S. Martin" <x512@pm.me>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Development Status :: 2 - Pre-Alpha
+Requires-Dist: numpy >=1.18.5
+Requires-Dist: pandas >=1.4
+Requires-Dist: requests >=2.20.0
+Requires-Dist: pyarrow >=14.0.1
+Requires-Dist: openpyxl >=3.0.3
+Requires-Dist: tabulate >=0.8.7
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: pytest-randomly ; extra == "dev"
+Requires-Dist: isort ; extra == "dev"
+Requires-Dist: nox ; extra == "dev"
+Project-URL: Homepage, https://github.com/x512/getfactormodels
+Provides-Extra: dev
+
+<a name="readme-top"></a>
+
+# getfactormodels
+
+![Python 3.11](https://img.shields.io/badge/Python-3.7+-306998.svg?logo=python&logoColor=ffde57&style=flat-square)
+
+
+Reliably retrieve data for various multi-factor asset pricing models.
+
+## Models
+
+- The 3-factor, 5-factor, and 6-factor models of Fama & French <sup>[[1]](#1) [[3]](#3) [[4]](#4)</sup>
+- Mark Carhart's 4-factor model <sup>[[2]](#2)</sup>
+- Pastor and Stambaugh's liquidity factors <sup>[[5]](#5)</sup>
+- Mispricing factors of Stambaugh and Yuan<sup>[[6]](#6)</sup>
+- The $q$*-factor* model of Hou, Mo, Xue and Zhang<sup>[[7]](#7)</sup>
+- The augmented $q^5$*-factor* model of  Hou, Mo, Xue and Zhang<sup>[[8]](#8)</sup>
+- *Intermediary Capital Ratio* (ICR) of He, Kelly & Manela<sup>[[9]](#9)</sup>
+- The *DHS behavioural factors* of Daniel, Hirshleifer & Sun<sup>[[10]](#10)</sup>
+- The *HML* $^{DEVIL}$ factor of Asness & Frazzini<sup>[[11]](#11)</sup>
+- The 6-factor model of Barillas and Shanken<sup>[[12]](#12)</sup>
+
+
+_Thanks to: Kenneth French, Robert Stambaugh, Lin Sun, Zhiguo He, AQR Capital Management (AQR.com) and Hou, Xue and Zhang (global-q.org), for their research and for the datasets they publically provide._
+
+
+## Installation
+
+`getfactormodels` requires Python ``>=3.7``
+
+* Install with pip:
+  ```shell
+  $ pip install getfactormodels   
+  ```
+
+## Usage
+
+#### Python
+
+After installing, import ``getfactormodels`` and call ``get_factors()`` with the ``model`` and ``frequency`` parameters. Optionally, specify a ``start_date`` and ``end_date``
+* For example, to retrieve the daily q-factor model data:
+
+    ```py
+    import getfactormodels as getfactormodels
+    
+    df = getfactormodels.get_factors(model='q', frequency='d')
+    ```
+    > _Trimmed output:_
+    ```txt
+    > df
+                 Mkt-RF      R_ME      R_IA     R_ROE      R_EG        RF
+    date                                                                  
+    1967-01-03  0.000778  0.004944  0.001437 -0.007118 -0.008563  0.000187
+    1967-01-04  0.001667 -0.003487 -0.000631 -0.002044 -0.000295  0.000187
+    1967-01-05  0.012990  0.004412 -0.005688  0.000838 -0.003075  0.000187
+    1967-01-06  0.007230  0.006669  0.008897  0.003603  0.002669  0.000187
+    1967-01-09  0.008439  0.006315  0.000331  0.004949  0.002979  0.000187
+    ...              ...       ...       ...       ...       ...       ...
+    2022-12-23  0.005113 -0.001045  0.004000  0.010484  0.003852  0.000161
+    2022-12-27 -0.005076 -0.001407  0.010190  0.009206  0.003908  0.000161
+    2022-12-28 -0.012344 -0.004354  0.000133 -0.010457 -0.004953  0.000161
+    2022-12-29  0.018699  0.008568 -0.008801 -0.012686 -0.002162  0.000161
+    2022-12-30 -0.002169  0.001840  0.001011 -0.004151 -0.003282  0.000161
+
+     [14096 rows x 6 columns]
+    ```
+
+    * or, retreive the monthly liquidity factors of Pastor and Stambaugh for the 1990s:
+
+    ```py
+      import getfactormodels as getfactormodels
+    
+      df = getfactormodels.get_factors(model='liquidity', frequency='m', start_date='1990-01-01', end_date='1999-12-31')
+    ```
+    > If you don't have time to type `liquidity`, type `liq`, or `ps`--there's a handy regex.
+
+    * or, saving the monthly 3-factor model of Fama & French to a file:
+
+    ```py
+      import getfactormodels as gfm
+
+      df = gfm.get_factors(model='ff3', frequency='m', output="ff3_data.csv")
+    ```
+     >The output parameter accepts a filename, path or directory, and can be one of csv, md, txt, xlsx, pkl.
+
+
+You can also import just the models that you need. 
+
+* For example, to import only the *ICR* and *q*-factor models: 
+
+    ```py
+      from getfactormodels import icr_factors, q_factors
+
+      # Passing a model function with no params defaults to monthly.
+      df = icr_factors()
+
+      # The 'q' models, and the 3-factor model of Fama-French also have weekly data.
+      df = q_factors(frequency="W", start_date="1992-01-01)
+    ```
+
+* If using ``ff_factors()``, then an additional ``model`` parameter should be specified:
+
+    ```py
+    from getfactormodels import ff_factors
+
+    # To get annual data for the 5-factor model:
+    data = ff_factors(model="5", frequency="Y", output=".xlsx")
+
+    # Daily 3-factor model data, since 1970 (not specifying an end date
+    # will return data up until today):
+    data = ff_factors(model="3", frequency="D", start_date="1970-01-01")
+    ```
+    > Output allows just an extension to be specified.
+
+* or import all the models:
+
+  ```py
+    from getfactormodels import models
+  ```
+
+* There's also the `FactorExtractor` class that the CLI uses (it doesn't really do a whole lot yet):
+
+  ```python
+    from getfactormodels import FactorExtractor
+
+    fe = FactorExtractor(model='carhart', frequency='m', start_date='1980-01-01', end_date='1980-05-01')
+    fe.get_factors()
+    fe.to_file('carhart_factors.md')
+    ```
+
+  * _The resulting ``carhart_factors.md`` file will look like this:_
+    
+    | date                |   Mkt-RF |     SMB |     HML |     MOM |     RF |
+    |:--------------------|---------:|--------:|--------:|--------:|-------:|
+    | 1980-01-31 00:00:00 |   0.0551 |  0.0162 |  0.0175 |  0.0755 | 0.008  |
+    | 1980-02-29 00:00:00 |  -0.0122 | -0.0185 |  0.0061 |  0.0788 | 0.0089 |
+    | 1980-03-31 00:00:00 |  -0.129  | -0.0664 | -0.0101 | -0.0955 | 0.0121 |
+    | 1980-04-30 00:00:00 |   0.0397 |  0.0105 |  0.0106 | -0.0043 | 0.0126 |
+
+
+#### Using the CLI
+* You can also use getfactormodels from the command line.
+
+    ```bash
+    $ getfactormodels -h
+
+    usage: getfactormodels [-h] -m MODEL [-f FREQ] [-s START] [-e END] [-o OUTPUT] [--no_rf]
+    ```
+
+* An example of how to use the CLI to retrieve the Fama-French 3-factor model data:
+    ```bash
+       getfactormodels --model ff3 --frequency M --start-date 1960-01-01 --end-date 2020-12-31 --output "filename.csv"
+    ```
+    > Accepted file extensions are .csv, .txt, .xlsx, and .md. If no extension is given, the output file will be .csv. The --output flag allows a filename, filepath or a directory. If only an extension is provided (including the . else it'll be passed as a filename), a name will be generated.
+    
+* Here's another example that retrieves the annual Fama-French 5-factor data without the RF column:
+
+  ```sh
+    getfactormodels -m 5 -f Y -s 1960-01-01 -e 2020-12-31 --no_rf -o ~/some_dir/filename.xlsx
+  ```
+    > `--no_rf` will return the factor model without an RF column.
+
+## References
+1. <a id="1"></a> E. F. Fama and K. R. French, ‘Common risk factors in the returns on stocks and bonds’, *Journal of Financial Economics*, vol. 33, no. 1, pp. 3–56, 1993. [PDF](https://people.duke.edu/~charvey/Teaching/BA453_2006/FF_Common_risk.pdf)
+2. <a id="2"></a> M. Carhart, ‘On Persistence in Mutual Fund Performance’, *Journal of Finance*, vol. 52, no. 1, pp. 57–82, 1997. [PDF](https://onlinelibrary.wiley.com/doi/full/10.1111/j.1540-6261.1997.tb03808.x)
+3. <a id="3"></a> E. F. Fama and K. R. French, ‘A five-factor asset pricing model’, *Journal of Financial Economics*, vol. 116, no. 1, pp. 1–22, 2015. [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2287202)
+4. <a id="4"></a> E. F. Fama and K. R. French, ‘Choosing factors’, *Journal of Financial Economics*, vol. 128, no. 2, pp. 234–252, 2018. [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2668236)
+5. <a id="5"></a>L. Pastor and R. Stambaugh, ‘Liquidity Risk and Expected Stock Returns’, *Journal of Political Economy*, vol. 111, no. 3, pp. 642–685, 2003. [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=279804)
+6. <a id="6"></a>R. F. Stambaugh and Y. Yuan, ‘Mispricing Factors’, *The Review of Financial Studies*, vol. 30, no. 4, pp. 1270–1315, 12 2016. [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2626701)
+7. <a id="7"></a>K. Hou, H. Mo, C. Xue, and L. Zhang, ‘Which Factors?’, *National Bureau of Economic Research, Inc*, 2014. [PDF](https://academic.oup.com/rof/article/23/1/1/5133564)
+8. <a id="8"></a>K. Hou, H. Mo, C. Xue, and L. Zhang, ‘An Augmented q-Factor Model with Expected Growth*’, *Review of Finance*, vol. 25, no. 1, pp. 1–41, 02 2020. [PDF](https://academic.oup.com/rof/article/25/1/1/5727769)
+9. <a id="9"></a>Z. He, B. Kelly, and A. Manela, ‘Intermediary asset pricing: New evidence from many asset classes’, *Journal of Financial Economics*, vol. 126, no. 1, pp. 1–35, 2017. [PDF](https://cpb-us-w2.wpmucdn.com/voices.uchicago.edu/dist/6/2325/files/2019/12/jfepublishedversion.pdf)
+10. <a id="10"></a>K. Daniel, D. Hirshleifer, and L. Sun, ‘Short- and Long-Horizon Behavioral Factors’, *Review of Financial Studies*, vol. 33, no. 4, pp. 1673–1736, 2020. [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3086063)
+11. <a id="11"></a>C. Asness and A. Frazzini, ‘The Devil in HML’s Details’, *The Journal of Portfolio Management*, vol. 39, pp. 49–68, 2013. [PDF](https://stockmarketmba.com/docs/Asness_Frazzini_AdjustHML.pdf)
+12. <a id="12"></a>F. Barillas and J. Shanken, ‘Comparing Asset Pricing Models’, *Journal of Finance*, vol. 73, no. 2, pp. 715–754, 2018. [PDF](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2700000)
+
+**Data sources:**
+
+* K. French, "Data Library," Tuck School of Business at Dartmouth.
+  [Link](https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html)
+* R. Stambaugh, "Liquidity" and "Mispricing" factor datasets, Wharton School, University of Pennsylvania.
+[Link](https://finance.wharton.upenn.edu/~stambaug/)
+* Z. He, "Intermediary Capital Ratio and Risk Factor" dataset, University of Chicago. 
+[Link](https://voices.uchicago.edu/zhiguohe/data-and-empirical-patterns/intermediary-capital-ratio-and-risk-factor/)
+* K. Hou, G. Xue, R. Zhang, "The Hou-Xue-Zhang q-factors data library," at global-q.org.
+[Link](http://global-q.org/factors.html)
+* AQR Capital Management's Data Sets.
+* Lin Sun, DHS Behavioural factors [Link](https://sites.google.com/view/linsunhome)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## License
+
+![License](https://img.shields.io/badge/MIT-blue?style=for-the-badge&logo=license&colorA=grey&colorB=blue)
+
+*The code in this project is released under the [MIT License]().*
+
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat-square&labelColor=ef8336)](https://pycqa.github.io/isort/)
+[![Ruff](https://img.shields.io/badge/-ruff-%23261230?style=flat-square&logo=ruff&logoColor=d7ff64)](https://simpleicons.org/?q=ruff)
+

getfactormodels-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+getfactormodels/__init__.py,sha256=OBR7bzlxouVp0fnnNiTPEu2Dg5WT7jY-Ss4AXhpPaQ0,1882
+getfactormodels/__main__.py,sha256=wog0NDpyKmUmFWJ0brIJIPoKN_m0HGXtLiXEuO3PrRs,5565
+getfactormodels/models/__init__.py,sha256=TuTNVPCEwd9xxlAHzoEk4sYDenYQcBdCiMbiulOT-Y0,1237
+getfactormodels/models/ff_models.py,sha256=8ek3Q40acyOuILcbiAJvYfPnyPisY4oPapeRf4w9FzI,4492
+getfactormodels/models/models.py,sha256=VdRWssoqKZKojJyzRj0KstXbLex7WfPU5bgN9NblQoE,17884
+getfactormodels/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+getfactormodels/utils/cli.py,sha256=Gtyuph2HCYgnx-qy6Aq4QRgDJzzxQ_bPX5iG463uJkE,1455
+getfactormodels/utils/utils.py,sha256=G-LcqJLWP-VGt3QlLsmQDwd7fbFK4itlNwpeADZRE_s,5559
+getfactormodels-0.0.1.dist-info/entry_points.txt,sha256=BeSOuEFV8LlnhTxpKpbeJLQfl_kS-bVif0k4Z1ghOnY,65
+getfactormodels-0.0.1.dist-info/LICENSE,sha256=3AA29XMl8p-SVQzn1hMvq478uj3FHVjEUknv6YaGeYk,1066
+getfactormodels-0.0.1.dist-info/WHEEL,sha256=EZbGkh7Ie4PoZfRQ8I0ZuP9VklN_TvcZ6DSE5Uar4z4,81
+getfactormodels-0.0.1.dist-info/METADATA,sha256=KKWEMEIvtRE--mXWonwR8Mwj05zxrKryyRtIwfmzbVg,11895
+getfactormodels-0.0.1.dist-info/RECORD,,

getfactormodels-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any

getfactormodels-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+getfactormodels=getfactormodels.__main__:main
+