pystock package — pystock 0.1.0 documentation

# pystock package

## Submodules

## pystock.exceptions module

exception pystock.exceptions.ColumnMismatch(message)

  Bases: `StockException`

  Exception raised for errors in the input.

  message -- explanation of the error

exception pystock.exceptions.ColumnNotFound(message)

  Bases: `StockException`

  Exception raised for errors in the input.

  message -- explanation of the error

exception pystock.exceptions.EmptyPortfolio(message)

  Bases: `StockException`

  Exception raised for errors in the input.

  message -- explanation of the error

exception pystock.exceptions.NoPortfolioCreated(message)

  Bases: `StockException`

  Exception raised for errors in the input.

  message -- explanation of the error

exception pystock.exceptions.NotLoadedError(message)

  Bases: `StockException`

  Exception raised for errors in the input.

  message -- explanation of the error

exception pystock.exceptions.PortfolioExists(message)

  Bases: `StockException`

  Exception raised for errors in the input.

  message -- explanation of the error

exception pystock.exceptions.StockException

  Bases: `Exception`

  Base class for all exceptions in this module.

## pystock.fff module

class pystock.fff.FamaFrenchFactors

  Bases: `object`

  calculate_mean_values()

    Returns the mean values of the factors.

    Returns:

      The mean values of the factors.

    Return type:

      pandas.DataFrame

  change_frequency(frequency='M')

    Changes the frequency of the data.

    Parameters:

      frequency (str, optional) – The frequency of the data. The default is “M”.

    Returns:

      The Fama French Factors data.

    Return type:

      pandas.DataFrame

  download(frequency='D', factors=3, directory='.', overwrite=False)

    download the Fama French Factors data.

    Parameters:

      - frequency (str, optional) – The frequency of the data. The default is “D”.

      - factors (int, optional) – The number of factors. The default is 3. Possible values are 3 and 5

      - directory (str, optional) – The directory to save the file. The default is “.”.

      - overwrite (bool, optional) – Whether to overwrite the file if it already exists. The default is False.

    Returns:

      The name of the file.

    Return type:

      str

  load(directory='.', frequency='M', factors=3, preprocess=True)

    Loads the Fama French Factors data.

    Parameters:

      - directory (str, optional) – The directory to save the file. The default is “.”.

      - frequency (str, optional) – The frequency of the data. The default is “M”.

      - factors (int, optional) – The number of factors. The default is 3. Possible values are 3 and 5

      - preprocess (bool, optional) – Whether to preprocess the data. The default is True.

    Returns:

      The Fama French Factors data.

    Return type:

      pandas.DataFrame

## pystock.models module

class pystock.models.Model(frequency='M', risk_free_rate=0.3333333333333333)

  Bases: `object`

  add_portfolio(portfolio: Portfolio, weights='equal', print_summary=False)

    Adds given the portfolio

    Parameters:

      - portfolio (Portfolio) – New portfolio

      - weights (list, optional) – List of weights of the stocks, by default None

      - print_summary (bool, optional) – Whether to print the summary of the portfolio, by default False

    Return type:

      None

  calculate_fff_params(factors=5, directory='.', frequency='M', column='Close', verbose=0, download=True)

    calculate the Fama-French factors using the same method as the portfolio

    Parameters:

      - factors (int, optional) – Number of factors, by default 5

      - directory (str, optional) – Directory to save the data, by default “.”

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

    Raises:

      ValueError – If no stocks in the portfolio

    Return type:

      None

  create_portfolio(benchmark_dir, benchmark_name, stock_dirs=None, stock_names=None, weights='equal', load_data=True, columns=['Adj Close'], frequency='M', rename_cols=['Close'], start_date=None, end_date=None, print_summary=True, **kwargs)

    Create a portfolio object from the data directories and adds it to the model

    Parameters:

      - benchmark_dir (str) – Directory of the benchmark

      - benchmark_name (str) – Name of the benchmark

      - stock_dirs (list, optional) – List of directories of the stocks, by default None

      - stock_names (list, optional) – List of names of the stocks, by default None

      - weights (list, optional) – List of weights of the stocks, by default “equal”

      - load_data (bool, optional) – Whether to load the data, by default True

      - columns (list, optional) – List of columns to be loaded, by default [“Adj Close”]

      - frequency (str, optional) – Frequency of the data, by default “M”

      - rename_cols (list, optional) – List of columns to be renamed, by default [“Close”]

      - start_date (str, optional) – Start date of the data, by default None

      - end_date (str, optional) – End date of the data, by default None

      - print_summary (bool, optional) – Whether to print the summary of the portfolio, by default True

      - **kwargs (dict) – Keyword arguments to be passed to the summary function

    Returns:

      Portfolio object

    Return type:

      Portfolio

  expected_return_of_stock(stock, model='capm')

    Calculate the expected return of a single stock

    Parameters:

      - stock (Stock) – Stock object

      - model (str, optional) – Model to use for calculating expected return, by default “capm”

    Return type:

      float

  get_risk_free_rate()

    Returns the risk free rate

  load_portfolio(columns=['Adj Close'], rename_cols=['Close'], frequency='M', start_date=None, end_date=None, print_summary=True, **kwargs)

    Loads the portfolio data

    Parameters:

      - columns (list, optional) – List of columns to be loaded, by default [“Adj Close”]

      - rename_cols (list, optional) – List of columns to be renamed, by default [“Close”]

      - frequency (str, optional) – Frequency of the data, by default “M”

      - start_date (str, optional) – Start date of the data, by default None

      - end_date (str, optional) – End date of the data, by default None

      - print_summary (bool, optional) – Whether to print the summary of the portfolio, by default True

      - **kwargs (dict) – Keyword arguments to be passed to the summary function

    Raises:

      NoPortfolioCreated – If no portfolio has been created yet

    Return type:

      None

  optimize_portfolio(model='capm', risk=0.5, can_short=False)

    Optimize the portfolio using scipy.optimize.minimize

    Parameters:

      - model (str) – Model to use for calculating expected returns. Supported models are ‘capm’ and ‘sim’

      - risk (float) – Risk of the portfolio

      - can_short (bool) – Whether the portfolio can short stocks

    Returns:

      Dictionary containing the optimized weights, expected return, variance and standard deviation

    Return type:

      dict

  portfolio_expected_value(weights, expected_returns)

    Get expected value of a portfolio

    Parameters:

      - weights (list) – Weights of the portfolio

      - expected_returns (list) – Expected returns of the stocks in the portfolio

    Returns:

      Expected value of the portfolio

    Return type:

      float

  portfolio_frontier(model='capm')

    Plots the portfolio frontier for two stocks. Assumes that the portfolio has only two stocks.

    Parameters:

      model (str) – Model to use for calculating expected returns. Supported models are ‘capm’ and ‘sim’

    Return type:

      None

  portfolio_info(weights='equal', model='capm')

    Get expected value, variance and standard deviation of a portfolio

    Parameters:

      - weights (list) – Weights of the portfolio

      - model (str) – Model to use for calculating expected returns. Supported models are ‘capm’ and ‘sim’

    Returns:

      Expected value, variance and standard deviation of the portfolio

    Return type:

      tuple

  portfolio_std(weights, cov_matrix)

    Get standard deviation of a portfolio

    Parameters:

      - weights (list) – Weights of the portfolio

      - cov_matrix (np.array) – Covariance matrix of the stocks in the portfolio

    Returns:

      Standard deviation of the portfolio

    Return type:

      float

  portfolio_variance(weights, cov_matrix)

    Get variance of a portfolio

    Parameters:

      - weights (list) – Weights of the portfolio

      - cov_matrix (np.array) – Covariance matrix of the stocks in the portfolio

    Returns:

      Variance of the portfolio

    Return type:

      float

  set_risk_free_rate(rate)

    Sets the risk free rate

  update_portfolio(portfolio: Portfolio, weights='equal', print_summary=False)

    Updates the portfolio to the new portfolio

    Parameters:

      - portfolio (Portfolio) – New portfolio

      - weights (list, optional) – List of weights of the stocks, by default “equal”

      - print_summary (bool, optional) – Whether to print the summary of the portfolio, by default False

    Return type:

      None

## pystock.portfolio module

class pystock.portfolio.Portfolio(benchmark_dir, benchmark_name, stock_dirs=None, stock_names=None, weights='equal')

  Bases: `object`

  Class for a portfolio of stocks. Contains a benchmark and a list of stocks. The class provides some useful methods for calculating the return of the portfolio.

  add_stocks(stocks=[], stock_dirs=None, stock_names=None, load_data=True, start_date=None, end_date=None, columns=None, frequency='D', rename_cols=None, overwrite=False)

    Add a stock to the list of stocks

    Parameters:

      - stocks (list, optional) – List of stocks, by default [] Not needed if stock_dirs is specified

      - stock_dirs (list) – List of stock directories

      - stock_names (list, optional) – List of stock names, by default None

      - load_data (bool, optional) – Whether to load the data, by default True

      - start_date (str, optional) – Start date, by default None

      - end_date (str, optional) – End date, by default None

      - columns (list, optional) – Columns to keep, by default None

      - frequency (str, optional) – Frequency of the data, by default “D”

      - rename_cols (list, optional) – Columns to rename, by default None

      - overwrite (bool, optional) – Whether to overwrite existing stocks, by default False

    Returns:

      stocks – List of stocks

    Return type:

      list

  all_stocks()

    Get all the stock data and names

    Returns:

      A tuple of List of stock data and name

    Return type:

      tuple

  benchmark_return(frequency='D', column='Close')

    Get the benchmark return

    Parameters:

      - freq (str, optional) – Frequency of the return, by default “D”

      - column (str, optional) – Column to calculate the return, by default “Close”

    Returns:

      Benchmark return

    Return type:

      pd.DataFrame

  calculate_fff_params(factors=5, directory='.', frequency='M', column='Close', verbose=0, download=True)

    calculate the Fama-French factors for regression

    Parameters:

      - factors (int, optional) – Number of factors, by default 5

      - directory (str, optional) – Directory to save the data, by default “.”

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

    Raises:

      ValueError – If no stocks in the portfolio

    Return type:

      None

  calculate_fff_params_one(stock, factors=5, directory='.', frequency='M', column='Close', verbose=0, download=True)

    calculate the Fama-French factors for regression

    Parameters:

      - stock (str) – Name of the stock

      - factors (int, optional) – Number of factors, by default 5

      - directory (str, optional) – Directory to save the data, by default “.”

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

  change_benchmark(benchmark_dir, benchmark_name, load=True, use_prev=True, start_date=None, end_date=None, columns=None, frequency='D', rename_cols=None)

    Change benchmark

    Parameters:

      - benchmark_dir (str) – Directory of the benchmark

      - benchmark_name (str) – Name of the benchmark

      - load (bool, optional) – Load the data, by default True

      - use_prev (bool, optional) – Use the values of start_date, end_date, columns, frequency, rename_cols from the previous benchmark, by default True

      - start_date (str, optional) – Start date, by default None

      - end_date (str, optional) – End date, by default None

      - columns (list, optional) – Columns to keep, by default None

      - frequency (str, optional) – Frequency of the data, by default “D”

      - rename_cols (list, optional) – Columns to rename, by default None

    Return type:

      None

  change_benchmark_frequency(frequency, change_stocks=True)

    Change the frequency of the benchmark data

    Parameters:

      - frequency (str) – Frequency of the data

      - change_stocks (bool, optional) – Whether to change the frequency of the stock data, by default True

    Return type:

      None

  download_fff_params(stock, factors=5, directory='.', frequency='M', overwrite=False)
  get_all_stock_params(how='inner', frequency='M', column='Close', return_dict=False)

    Get the stock data and the benchmark data

    Parameters:

      - how (str, optional) – How to merge the data, by default “inner”

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

      - return_dict (bool, optional) – Return a dictionary instead of a dataframe, by default False

    Returns:

      stock alpha and beta

    Return type:

      pd.DataFrame

  get_all_stock_returns(frequency='M', column='Close')

    Get the stock returns

    Parameters:

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

    Returns:

      Stock returns

    Return type:

      pd.DataFrame

  get_cov_matrix(column='Close', frequency='M')

    Calculates the covariance matrix of the stocks in the portfolio

    Parameters:

      - column (str, optional) – Column to calculate the covariance matrix of, by default “Close”

      - frequency (str, optional) – Frequency of the data, by default “M”

    Returns:

      Covariance matrix

    Return type:

      pd.DataFrame

  get_portfolio_return(frequency='M', column='Close', weights='equal')

    Get the portfolio return

    Parameters:

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

      - weights (list) – List of weights

    Returns:

      Portfolio return

    Return type:

      float

  get_stock_params(name, how='inner', frequency='M', column='Close')

    Get the stock data and the benchmark data

    Parameters:

      - name (str) – Name of the stock

      - how (str, optional) – How to merge the data, by default “inner”

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column of the data, by default “Close”

    Returns:

      - pd.DataFrame – Stock data

      - pd.DataFrame – Benchmark data

  get_stock_return(name, frequency='M', column='Close')

    Get the stock returns

    Parameters:

      - name (str) – Name of the stock

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

    Returns:

      Stock return and volatility

    Return type:

      tuple

  load_all(start_date=None, end_date=None, columns=None, frequency='D', rename_cols=None, overwrite=False)

    Load stock data

    Parameters:

      - start_date (str, optional) – Start date, by default None

      - end_date (str, optional) – End date, by default None

      - columns (list, optional) – Columns to keep, by default None

      - frequency (str, optional) – Frequency of the data, by default “D”

      - rename_cols (list, optional) – Columns to rename, by default None

      - overwrite (bool, optional) – Overwrite existing data, by default False

    Returns:

      Stock data

    Return type:

      pd.DataFrame

  load_benchmark(start_date=None, end_date=None, columns=None, frequency='D', rename_cols=None)

    Load benchmark data

    Parameters:

      - start_date (str, optional) – Start date, by default None

      - end_date (str, optional) – End date, by default None

      - columns (list, optional) – Columns to keep, by default None which means keep all columns

      - frequency (str, optional) – Frequency of the data, by default “D”

      - rename_cols (list, optional) – Columns to rename, by default None

    Returns:

      Benchmark data

    Return type:

      pd.DataFrame

  load_one_stock(name, start_date=None, end_date=None, columns=None, frequency='D', rename_cols=None, overwrite=False)

    Loads one stock data and returns it

    Parameters:

      - name (str) – Name of the stock

      - start_date (str, optional) – Start date, by default None

      - end_date (str, optional) – End date, by default None

      - columns (list, optional) – Columns to keep, by default None

      - freq (str, optional) – Frequency of the data, by default “D”

      - rename_cols (list, optional) – Columns to rename, by default None

      - overwrite (bool, optional) – Overwrite the data, by default False

    Returns:

      Stock data

    Return type:

      pd.DataFrame

  merge_all()

    Merge all the stock data

    Returns:

      Merged data

    Return type:

      pd.DataFrame

  merge_stock_with_benchmark(name, how='inner')

    Merge the stock data with the benchmark data

    Parameters:

      - name (str) – Name of the stock

      - how (str, optional) – How to merge the data, by default “inner”

    Returns:

      Merged data

    Return type:

      pd.DataFrame

  remove_stocks(names)

    Remove a stock from the list of stocks

    Parameters:

      stock_name (str) – Name of the stock

  set_weights(weights='equal')

    Creates weights for the stocks

    Parameters:

      weights (str or list or np.ndarray, optional) – Type of weights to create, by default “equal”

    Returns:

      Weights of the stocks

    Return type:

      np.ndarray

  summary(frequency='M', column='Close', weights='equal', just_load=False)

    Get the portfolio return

    Parameters:

      - frequency (str, optional) – Frequency of the data, by default “M”

      - column (str, optional) – Column to use, by default “Close”

      - weights (list) – List of weights

    Returns:

      Portfolio return

    Return type:

      float

class pystock.portfolio.Stock(name, directory)

  Bases: `object`

  A class to represent a stock. Have methods to load data from a csv file and calculate the return of the stock.

  calculate_fff(column='Close', verbose=1)

    Calculates the fama french factors

    Parameters:

      - column (str, optional) – Column to calculate the fama french factors on, by default “Close”

      - verbose (int, optional) – Verbosity, by default 1

    Raises:

      NotLoadedError – If the stock data or fama french factors are not loaded

    Returns:

      Fama french factors

    Return type:

      pd.Series

  change_frequency(frequency)

    Changes the frequency of the data.

    Parameters:

      frequency (str) – Frequency of the data

  download_fff(frequency='D', factors=3, directory='.', overwrite=False, load=True)

    Downloads the fama french factors

  freq_return(frequency='M', mean=True, column='Close')

    Calculates the return of the stock for a given frequency

    Parameters:

      - frequency (str, optional) – Frequency of the data, by default “D”

      - mean (bool, optional) – Whether to return the mean of the return, by default True

      - column (str, optional) – Column to calculate the return, by default “Close”

    Returns:

      Return of the stock

    Return type:

      float

  load_data(start_date=None, end_date=None, columns=None, frequency='M', rename_cols=None)

    Read data from a csv file and return a dataframe. Assumes that the dataframe has column Date containing dates.

    Parameters:

      - start_date (str, optional) – Start date of the data, by default None

      - end_date (str, optional) – End date of the data, by default None

      - columns (list, optional) – Columns to keep, by default None which means keep all columns

      - frequency (str, optional) – Frequency of the data, by default “D”

      - rename_cols (list, optional) – Columns to rename, by default None

    Return type:

      pd.DataFrame

  load_fff(frequency='M', factors=5, directory='.')

    Loads the fama french factors

## pystock.utils module

pystock.utils.bigger_frequency(freq1, freq2)

  Check if freq1 is a bigger frequency than freq2

  Parameters:

    - freq1 (str) – Frequency 1

    - freq2 (str) – Frequency 2

  Returns:

    True if freq1 is bigger than freq2

  Return type:

    bool

pystock.utils.convert_str_to_date(string, format='%Y-%m-%d')

  Convert string to date

  Parameters:

    - string (str) – String to convert

    - format (str, optional) – Format of the string, by default “%Y-%m-%d”

  Returns:

    Date

  Return type:

    datetime.date

pystock.utils.create_weight(num_stock, weight_type='equal')

  Create a list of weights for a portfolio with num_stock stocks

  Parameters:

    num_stock (int) – Number of stocks in the portfolio

  Returns:

    List of weights

  Return type:

    list

pystock.utils.load_data(directory, start_date=None, end_date=None, columns=None, frequency='D', rename_cols=None)

  Read data from a csv file and return a dataframe. Assumes that the dataframe has column Date containing dates.

  Parameters:

    - start_date (str, optional) – Start date of the data, by default None

    - end_date (str, optional) – End date of the data, by default None

    - columns (list, optional) – Columns to keep, by default None which means keep all columns

    - frequency (str, optional) – Frequency of the data, by default “D”

    - rename_cols (list, optional) – Columns to rename, by default None

  Return type:

    pd.DataFrame

pystock.utils.merge_dfs(dfs, df_names=None, join='inner')

  Merges a list of dataframes into one. Uses the index as the key and pd.concat to merge the dataframes

  Parameters:

    - dfs (list) – List of dataframes to merge

    - df_names (list, optional) – Names of the dataframes, by default None Uses this to rename the columns of the merged dataframe

    - join (str, optional) – How to join the dataframes, by default “inner”

  Returns:

    Merged dataframe

  Return type:

    pd.DataFrame

## Module contents