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_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