okama.AssetList

class AssetList(assets=None, *, first_date=None, last_date=None, ccy='USD', inflation=True)

Bases: ListMaker

The list of financial assets implementation.

AssetList can include stocks, ETF, mutual funds, commodities, currencies and stock indexes (benchmarks).

Parameters:

assetslist, default None: List of assets. Could include tickers or asset like objects (Asset, Portfolio). If None a single asset list with a default ticker is used.
first_datestr, default None: First date of monthly return time series. If None the first date is calculated automatically as the oldest available date for the listed assets.
last_datestr, default None: Last date of monthly return time series. If None the last date is calculated automatically as the newest available date for the listed assets.
ccystr, default ‘USD’: Base currency for the list of assets. All risk metrics and returns are adjusted to the base currency.
inflationbool, default True: Defines whether to take inflation data into account in the calculations. Including inflation could limit available data (last_date, first_date) as the inflation data is usually published with a one-month delay. With inflation = False some properties like real return are not available.

Methods & Attributes

`annual_return_ts`	Calculate annual rate of return time series for each asset.
`currency`	Return the base currency of the Asset List.
`describe`([years, tickers])	Generate descriptive statistics for a list of assets.
`dividend_growing_years`	Return the number of years when the annual dividend was growing for each asset.
`dividend_paying_years`	Return the number of years of consecutive dividend payments for each asset.
`dividend_yield`	Calculate last twelve months (LTM) dividend yield time series (monthly) for each asset.
`dividend_yield_annual`	Calculate last twelve months (LTM) dividend yield annual time series.
`dividends_annual`	Return calendar year dividends sum time series for each asset.
`drawdowns`	Calculate drawdowns time series for the assets.
`get_cagr`([period, real])	Calculate assets Compound Annual Growth Rate (CAGR) for a given trailing period.
`get_cumulative_return`([period, real])	Calculate cumulative return over a given trailing period for each asset.
`get_cvar_historic`([time_frame, level])	Calculate historic Conditional Value at Risk (CVAR, expected shortfall) for the assets with a given timeframe.
`get_dividend_mean_growth_rate`([period])	Calculate geometric mean of annual dividends growth rate time series for a given trailing period.
`get_dividend_mean_yield`([period])	Calculate the arithmetic mean for annual dividend yield (LTM) over a specified period.
`get_rolling_cagr`([window, real])	Calculate rolling CAGR for each asset.
`get_rolling_cumulative_return`([window, real])	Calculate rolling cumulative return for each asset.
`get_rolling_risk_annual`([window])	Calculate annualized risk rolling time series for each asset.
`get_sharpe_ratio`([rf_return])	Calculate Sharpe ratio for the assets.
`get_sortino_ratio`([t_return])	Calculate Sortino ratio for the assets with specified target return.
`get_var_historic`([time_frame, level])	Calculate historic Value at Risk (VaR) for the assets with a given timeframe.
`index_beta`([rolling_window])	Compute beta coefficient time series for the assets.
`index_corr`([rolling_window])	Compute correlation with the index (or benchmark) time series for the assets.
`jarque_bera`	Perform Jarque-Bera test for normality of assets returns historical data.
`kstest`([distr])	Perform Kolmogorov-Smirnov test for goodness of fit the asset returns to a given distribution.
`kurtosis`	Calculate expanding Fisher (normalized) kurtosis of the return time series for each asset.
`kurtosis_rolling`([window])	Calculate rolling Fisher (normalized) kurtosis of the return time series for each asset.
`mean_return`	Calculate annualized mean return (arithmetic mean) for the rate of return time series (each asset).
`plot_assets`([kind, tickers, pct_values, xy_text])	Plot the assets points on the risk-return chart with annotations.
`real_mean_return`	Calculate annualized real mean return (arithmetic mean) for the rate of return time series (each assets).
`recovery_periods`	Calculate the longest recovery periods for the assets.
`risk_annual`	Calculate annualized risk expanding time series for each asset.
`risk_monthly`	Calculate monthly risk expanding time series for each asset.
`semideviation_annual`	Return semideviation annualized values for each asset.
`semideviation_monthly`	Calculate semi-deviation monthly values for each asset.
`skewness`	Compute expanding skewness of the return time series for each asset returns.
`skewness_rolling`([window])	Compute rolling skewness of the return time series for each asset.
`symbols`	Return a list of financial symbols used to set the AssetList.
`tickers`	Return a list of tickers (symbols without a namespace) used to set the AssetList.
`tracking_difference`([rolling_window])	Return tracking difference for the rate of return of assets.
`tracking_difference_annual`	Calculate tracking difference for each calendar year.
`tracking_difference_annualized`([rolling_window])	Calculate annualized tracking difference time series for the rate of return of assets.
`tracking_error`([rolling_window])	Calculate tracking error time series for the rate of return of assets.
`wealth_indexes`	Calculate wealth index time series for the assets and accumulated inflation.

property wealth_indexes

Calculate wealth index time series for the assets and accumulated inflation.

Wealth index (Cumulative Wealth Index) is a time series that presents the value of each asset over historical time period. Accumulated inflation time series is added if inflation=True in the AssetList.

Wealth index is obtained from the accumulated return multiplicated by the initial investments. That is: 1000 * (Acc_Return + 1) Initial investments are taken as 1000 units of the AssetList base currency.

Returns:

DataFrame: Time series of wealth index values for each asset and accumulated inflation.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SPY.US', 'BND.US'])
>>> x.wealth_indexes.plot()
>>> plt.show()

property risk_monthly

Calculate monthly risk expanding time series for each asset.

Monthly risk of the asset is a standard deviation of the rate of return time series. Standard deviation (sigma σ) is normalized by N-1.

Monthly risk is calculated for the rate of retirun time series for the sample from ‘first_date’ to ‘last_date’.

Returns:

DataFrame: Monthly risk (standard deviation) expanding time series for each asset in form of Series.

See also

risk_annual: Calculate annualized risks expanding time series.
semideviation_monthly: Calculate semideviation monthly values.
semideviation_annual: Calculate semideviation annualized values.
get_var_historic: Calculate historic Value at Risk (VaR).
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).
drawdowns: Calculate drawdowns.

Examples

>>> al = ok.AssetList(['GC.COMM', 'SHV.US'], ccy='USD', last_date='2021-01')
>>> al.risk_monthly
Symbols   GC.COMM    SHV.US
date
2007-03  0.025668  0.000141
2007-04  0.020872  0.000153
2007-05  0.027513  0.000451
2007-06  0.025988  0.000406
           ...       ...
2020-09  0.051006  0.001380
2020-10  0.050861  0.001377

property risk_annual

Calculate annualized risk expanding time series for each asset.

Risk is a standard deviation of the rate of return.

Annualized risk time series is calculated for the rate of return from ‘first_date’ to ‘last_date’ (expanding).

Returns:

DataFrame: Annualized risk (standard deviation) expanding time series for each asset.

See also

risk_monthly: Calculate montly risk expanding time series for each asset.
get_rolling_risk_annual: Calculate annualized risk rolling time series.
semideviation_monthly: Calculate semideviation monthly values.
semideviation_annual: Calculate semideviation annualized values.
get_var_historic: Calculate historic Value at Risk (VaR).
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).
drawdowns: Calculate assets drawdowns.

Notes

CFA recomendations are used to annualize risk values [1].

[1]

What’s Wrong with Multiplying by the Square Root of Twelve. Paul D. Kaplan, CFA Institute Journal Review, 2013

Examples

>>> al = ok.AssetList(['GC.COMM', 'SHV.US'], ccy='USD', last_date='2021-01')
>>> al.risk_annual
GC.COMM    0.195236
SHV.US     0.004960
dtype: float64

get_rolling_risk_annual(window=12)

Calculate annualized risk rolling time series for each asset.

Risk is a standard deviation of the rate of return.

Annualized risk time series is calculated for the rate of return values limited by moving window.

Parameters:

windowint, default 12: Size of the moving window in months.

Returns:

DataFrame: Annualized risk (standard deviation) rolling time series for each asset.

See also

risk_monthly: Calculate montly risk expanding time series for each asset.
risk_annual: Calculate annualized risks.
semideviation_monthly: Calculate semideviation monthly values.
semideviation_annual: Calculate semideviation annualized values.
get_var_historic: Calculate historic Value at Risk (VaR).
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).
drawdowns: Calculate assets drawdowns.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SPY.US', 'AGG.US'], ccy='USD', inflation=True)
>>> x.get_rolling_risk_annual(window=5*12).plot()
>>> plt.show()

property semideviation_monthly

Calculate semi-deviation monthly values for each asset.

Semi-deviation (Downside risk) is the risk of the return being below the expected return.

Semi-deviation is calculated for rate of retirun time series for the sample from ‘first_date’ to ‘last_date’.

Returns:

Series: Monthly semideviation values for each asset in form of Series.

See also

risk_monthly: Calculate montly risk for each asset.
risk_annual: Calculate annualized risks.
semideviation_annual: Calculate semideviation annualized values.
get_var_historic: Calculate historic Value at Risk (VaR).
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).
drawdowns: Calculate drawdowns.

Examples

>>> al = ok.AssetList(['GC.COMM', 'SHV.US'], ccy='USD', last_date='2021-01')
>>> al.semideviation_monthly
GC.COMM    0.039358
SHV.US     0.000384
dtype: float64

property semideviation_annual

Return semideviation annualized values for each asset.

Semi-deviation (Downside risk) is the risk of the return being below the expected return.

Semi-deviation is calculated for rate of retirun time series for the sample from ‘first_date’ to ‘last_date’.

Returns:

Series: Annualized semideviation values for each asset in form of Series.

See also

risk_monthly: Calculate montly risk for each asset.
risk_annual: Calculate annualized risks.
semideviation_monthly: Calculate semideviation monthly values.
get_var_historic: Calculate historic Value at Risk (VaR).
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).
drawdowns: Calculate drawdowns.

Examples

>>> al = ok.AssetList(['GC.COMM', 'SHV.US'], ccy='USD', last_date='2021-01')
>>> al.semideviation_annual
GC.COMM    0.115302
SHV.US     0.000560
dtype: float64

get_var_historic(time_frame=12, level=1)

Calculate historic Value at Risk (VaR) for the assets with a given timeframe.

The VaR calculates the potential loss of an investment with a given time frame and confidence level. Loss is a positive number (expressed in cumulative return). If VaR is negative there are expected gains at this confidence level.

Parameters:

time_frameint, default 12: Time period size in months
levelint, default 1: Confidence level in percents. Default value is 1%.

Returns:

Series: VaR values for each asset in form of Series.

See also

risk_monthly: Calculate montly risk for each asset.
risk_annual: Calculate annualized risks.
semideviation_monthly: Calculate semideviation monthly values.
semideviation_annual: Calculate semideviation annualized values.
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).
drawdowns: Calculate drawdowns.

Examples

>>> x = ok.AssetList(['SPY.US', 'AGG.US'])
>>> x.get_var_historic(time_frame=60, level=1)
SPY.US    0.2101
AGG.US    -0.0867
Name: VaR, dtype: float64

get_cvar_historic(time_frame=12, level=1)

Calculate historic Conditional Value at Risk (CVAR, expected shortfall) for the assets with a given timeframe.

CVaR is the average loss over a specified time period of unlikely scenarios beyond the confidence level. Loss is a positive number (expressed in cumulative return). If CVaR is negative there are expected gains at this confidence level.

Parameters:

time_frameint, default 12: Time period size in months
levelint, default 1: Confidence level in percents to calculate the VaR. Default value is 1% (1% quantile).

Returns:

Series: CVaR values for each asset in form of Series.

See also

risk_monthly: Calculate montly risk for each asset.
risk_annual: Calculate annualized risks.
semideviation_monthly: Calculate semideviation monthly values.
semideviation_annual: Calculate semideviation annualized values.
get_var_historic: Calculate historic Value at Risk (VaR).
drawdowns: Calculate drawdowns.

Examples

>>> x = ok.AssetList(['SPY.US', 'AGG.US'])
>>> x.get_cvar_historic(time_frame=60, level=1)
SPY.US    0.2574
AGG.US   -0.0766
dtype: float64
Name: VaR, dtype: float64

property drawdowns

Calculate drawdowns time series for the assets.

The drawdown is the percent decline from a previous peak in wealth index.

Returns:

DataFrame: Time series of drawdowns.

See also

risk_monthly: Calculate montly risk for each asset.
risk_annual: Calculate annualized risks.
semideviation_monthly: Calculate semideviation monthly values.
semideviation_annual: Calculate semideviation annualized values.
get_var_historic: Calculate historic Value at Risk (VaR).
get_cvar_historic: Calculate historic Conditional Value at Risk (CVaR).

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['SPY.US', 'BND.US'], last_date='2021-08')
>>> al.drawdowns.plot()
>>> plt.show()

property recovery_periods

Calculate the longest recovery periods for the assets.

The recovery period (drawdown duration) is the number of months to reach the value of the last maximum.

Returns:

Series: Max recovery period for each asset (in months).

See also

drawdowns: Calculate drawdowns time series.

Notes

If the last asset maximum value is not recovered NaN is returned. The largest recovery period does not necessary correspond to the max drawdown.

Examples

>>> x = ok.AssetList(['SPY.US', 'AGG.US'])
>>> x.recovery_periods
SPY.US    52
AGG.US    15
dtype: int32

get_cagr(period=None, real=False)

Calculate assets Compound Annual Growth Rate (CAGR) for a given trailing period.

Compound annual growth rate (CAGR) is the rate of return that would be required for an investment to grow from its initial to its final value, assuming all incomes were reinvested.

Inflation adjusted annualized returns (real CAGR) are shown with real=True option.

Annual inflation value is calculated for the same period if inflation=True in the AssetList.

Parameters:

period: int, optional: CAGR trailing period in years. None for the full time CAGR.
real: bool, default False: CAGR is adjusted for inflation (real CAGR) if True. AssetList should be initiated with Inflation=True for real CAGR.

Returns:

Series: CAGR values for each asset and annualized inflation (optional).

See also

get_rolling_cagr: Calculate rolling CAGR.

Notes

CAGR is not defined for periods less than 1 year (NaN values are returned).

Examples

>>> x = ok.AssetList()
>>> x.get_cagr(period=5)
SPY.US    0.1510
USD.INFL   0.0195
dtype: float64

To get inflation adjusted return (real annualized return) add real=True option:

>>> x = ok.AssetList(['EURUSD.FX', 'CNYUSD.FX'], inflation=True)
>>> x.get_cagr(period=5, real=True)
EURUSD.FX    0.000439
CNYUSD.FX   -0.017922
dtype: float64

get_rolling_cagr(window=12, real=False)

Calculate rolling CAGR for each asset.

Compound annual growth rate (CAGR) is the rate of return that would be required for an investment to grow from its initial to its final value, assuming all incomes were reinvested.

Inflation adjusted annualized returns (real CAGR) are shown with real=True option.

Parameters:

windowint, default 12: Size of the moving window in months. Window size should be at least 12 months for CAGR.
real: bool, default False: CAGR is adjusted for inflation (real CAGR) if True. AssetList should be initiated with Inflation=True for real CAGR.

Returns:

DataFrame: Time series of rolling CAGR and mean inflation (optionally).

See also

get_rolling_cagr: Calculate rolling CAGR.
get_cagr: Calculate CAGR.
get_rolling_cumulative_return: Calculate rolling cumulative return.
annual_return: Calculate annualized mean return (arithmetic mean).

Notes

CAGR is not defined for periods less than 1 year (NaN values are returned).

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SPY.US', 'AGG.US'], ccy='USD', inflation=True)
>>> x.get_rolling_cagr(window=5*12).plot()
>>> plt.show()

For inflation adjusted rolling CAGR add ‘real=True’ option:

>>> x.get_rolling_cagr(window=5*12, real=True).plot()
>>> plt.show()

get_cumulative_return(period=None, real=False)

Calculate cumulative return over a given trailing period for each asset.

The cumulative return is the total change in the asset price during the investment period.

Inflation adjusted cumulative returns (real cumulative returns) are shown with real=True option. Annual inflation data is calculated for the same period if inflation=True in the AssetList.

Parameters:

period: str, int or None, default None: Trailing period in years. Period should be more then 0. None - full time cumulative return. ‘YTD’ - (Year To Date) period of time beginning the first day of the calendar year up to the last month.
real: bool, default False: Cumulative return is adjusted for inflation (real cumulative return) if True. AssetList should be initiated with Inflation=True for real cumulative return.

Returns:

Series: Cumulative return values for each asset and cumulative inflation (if inflation=True in AssetList).

See also

get_rolling_cagr: Calculate rolling CAGR.
get_cagr: Calculate CAGR.
get_rolling_cumulative_return: Calculate rolling cumulative return.
annual_return: Calculate annualized mean return (arithmetic mean).

Examples

>>> x = ok.AssetList(['MCFTR.INDX'], ccy='RUB')
>>> x.get_cumulative_return(period='YTD')
MCFTR.INDX   0.1483
RUB.INFL     0.0485
dtype: float64

get_rolling_cumulative_return(window=12, real=False)

Calculate rolling cumulative return for each asset.

The cumulative return is the total change in the asset price.

Parameters:

windowint, default 12: Size of the moving window in months.
real: bool, default False: Cumulative return is adjusted for inflation (real cumulative return) if True. AssetList should be initiated with Inflation=True for real cumulative return.

Returns:

DataFrame: Time series of rolling cumulative return.

See also

get_rolling_cagr: Calculate rolling CAGR.
get_cagr: Calculate CAGR.
get_cumulative_return: Calculate cumulative return.
annual_return: Calculate annualized mean return (arithmetic mean).

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SPY.US', 'AGG.US'], ccy='USD', inflation=True)
>>> x.get_rolling_cumulative_return(window=5*12).plot()
>>> plt.show()

For inflation adjusted rolling cumulative return add ‘real=True’ option:

>>> x.get_rolling_cumulative_return(window=5*12, real=True).plot()
>>> plt.show()

property annual_return_ts

Calculate annual rate of return time series for each asset.

Rate of return is calculated for each calendar year.

Returns:

DataFrame: Calendar annual rate of return time series.

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['SPY.US', 'BND.US'], last_date='2021-08')
>>> al.annual_return_ts.plot(kind='bar')
>>> plt.show()

describe(years=(1, 5, 10), tickers=True)

Generate descriptive statistics for a list of assets.

Statistics includes:

YTD (Year To date) compound return
CAGR for a given list of periods and full available period
Annualized mean rate of return (full available period)
LTM Dividend yield - last twelve months dividend yield

Risk metrics (full period):

risk (standard deviation)
CVAR (timeframe is 1 year)
max drawdowns (and dates of the drawdowns)

Statistics also shows for each asset: - inception date - first date available for each asset - last asset date - available for each asset date - Common last data date - common for the asset list data (may be set by last_date manually)

Parameters:

yearstuple of (int,), default (1, 5, 10): List of periods for CAGR.
tickersbool, default True: Defines whether show tickers (True) or assets names in the header.

Returns:

DataFrame: Table of descriptive statistics for a list of assets.

See also

get_cumulative_return: Calculate cumulative return.
get_cagr: Calculate assets Compound Annual Growth Rate (CAGR).
dividend_yield: Calculate dividend yield (LTM).
risk_annual: Return annualized risks (standard deviation).
get_cvar: Calculate historic Conditional Value at Risk (CVAR, expected shortfall).
drawdowns: Calculate drawdowns.

Examples

>>> al = ok.AssetList(['SPY.US', 'AGG.US'], last_date='2021-08')
>>> al.describe(years=[1, 10, 15])
                 property               period    AGG.US    SPY.US inflation
       Compound return                  YTD -0.005620  0.180519  0.048154
                  CAGR              1 years -0.007530  0.363021  0.053717
                  CAGR             10 years  0.032918  0.152310  0.019136
                  CAGR             15 years  0.043013  0.107598  0.019788
                  CAGR  17 years, 10 months  0.039793  0.107972  0.022002
        Dividend yield                  LTM  0.018690  0.012709       NaN
                  Risk  17 years, 10 months  0.037796  0.158301       NaN
                  CVAR  17 years, 10 months  0.023107  0.399398       NaN

property mean_return

Calculate annualized mean return (arithmetic mean) for the rate of return time series (each asset).

Mean return calculated for the full history period. Arithmetic mean for the inflation is also shown if there is an inflation=True option in AssetList.

Returns:

Series: Mean return value for each asset.

Examples

>>> x = ok.AssetList(['MCFTR.INDX', 'RGBITR.INDX'], ccy='RUB', inflation=True)
>>> x.mean_return
MCFTR.INDX     0.209090
RGBITR.INDX    0.100133
dtype: float64

property real_mean_return

Calculate annualized real mean return (arithmetic mean) for the rate of return time series (each assets).

Real rate of return is adjusted for inflation. Real return is defined if there is an inflation=True option in AssetList.

Returns:

Series: Mean real return value for each asset.

Examples

>>> x = ok.AssetList(['MCFTR.INDX', 'RGBITR.INDX'], ccy='RUB', inflation=True)
>>> x.real_mean_return
MCFTR.INDX     0.118116
RGBITR.INDX    0.017357
dtype: float64

property dividend_yield

Calculate last twelve months (LTM) dividend yield time series (monthly) for each asset.

LTM dividend yield is the sum trailing twelve months of common dividends per share divided by the current price per share.

All yields are calculated in the asset list base currency after adjusting the dividends and price time series. Forecasted (future) dividends are removed. Zero value time series are created for assets without dividends.

Returns:

DataFrame: Time series of LTM dividend yield for each asset.

See also

dividend_yield_annual: Calendar year dividend yield time series.
dividends_annual: Calendar year dividends time series.
dividend_paying_years: Number of years of consecutive dividend payments.
dividend_growing_years: Number of years when the annual dividend was growing.
get_dividend_mean_yield: Arithmetic mean for annual dividend yield.
get_dividend_mean_growth_rate: Geometric mean of annual dividends growth rate.

Examples

>>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='1984-01', last_date='1994-12')
>>> x.dividend_yield
           T.US    XOM.US
1984-01  0.000000  0.000000
1984-02  0.000000  0.002597
1984-03  0.002038  0.002589
1984-04  0.001961  0.002346
           ...       ...
1994-09  0.018165  0.012522
1994-10  0.018651  0.011451
1994-11  0.018876  0.012050
1994-12  0.019344  0.011975
[132 rows x 2 columns]

property dividends_annual

Return calendar year dividends sum time series for each asset.

Returns:

DataFrame: Annual dividends time series for each asset.

See also

dividend_yield: Dividend yield time series.
dividend_yield_annual: Calendar year dividend yield time series.
dividend_paying_years: Number of years of consecutive dividend payments.
dividend_growing_years: Number of years when the annual dividend was growing.
get_dividend_mean_yield: Arithmetic mean for annual dividend yield.
get_dividend_mean_growth_rate: Geometric mean of annual dividends growth rate.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='2010-01', last_date='2020-12')
>>> x.dividends_annual.plot(kind='bar')
>>> plt.show()

property dividend_yield_annual

Calculate last twelve months (LTM) dividend yield annual time series.

Time series is based on the dividend yield for the end of calendar year.

LTM dividend yield is the sum trailing twelve months of common dividends per share divided by the current price per share.

All yields are calculated in the asset list base currency after adjusting the dividends and price time series. Forecasted (future) dividends are removed.

Returns:

DataFrame: Time series of LTM dividend yield for each asset.

See also

dividend_yield: Dividend yield time series.
dividends_annual: Calendar year dividends time series.
dividend_paying_years: Number of years of consecutive dividend payments.
dividend_growing_years: Number of years when the annual dividend was growing.
get_dividend_mean_yield: Arithmetic mean for annual dividend yield.
get_dividend_mean_growth_rate: Geometric mean of annual dividends growth rate.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='2010-01', last_date='2020-12')
>>> x.dividend_yield_annual.plot(kind='bar')
>>> plt.show()

property dividend_growing_years

Return the number of years when the annual dividend was growing for each asset.

Returns:

DataFrame: Dividend growth length periods time series for each asset.

See also

dividend_yield: Dividend yield time series.
dividend_yield_annual: Calendar year dividend yield time series.
dividends_annual: Calendar year dividends.
dividend_paying_years: Number of years of consecutive dividend payments.
get_dividend_mean_yield: Arithmetic mean for annual dividend yield.
get_dividend_mean_growth_rate: Geometric mean of annual dividends growth rate.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='1984-01', last_date='1994-12')
>>> x.dividend_growing_years.plot(kind='bar')
>>> plt.show()

property dividend_paying_years

Return the number of years of consecutive dividend payments for each asset.

Returns:

DataFrame: Dividend payment period length time series for each asset.

See also

dividend_yield: Dividend yield time series.
dividend_yield_annual: Calendar year dividend yield time series.
dividends_annual: Calendar year dividends.
dividend_growing_years: Number of years when the annual dividend was growing.
get_dividend_mean_yield: Arithmetic mean for annual dividend yield.
get_dividend_mean_growth_rate: Geometric mean of annual dividends growth rate.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='1984-01', last_date='1994-12')
>>> x.dividend_paying_years.plot(kind='bar')
>>> plt.show()

get_dividend_mean_growth_rate(period=5)

Calculate geometric mean of annual dividends growth rate time series for a given trailing period.

Growth rate is taken for full calendar annual dividends.

Parameters:

periodint, default 5: Growth rate trailing period in years. Period should be a positive integer and not exceed the available data period_length.

Returns:

Series: Dividend growth geometric mean value for each asset.

See also

dividend_yield: Dividend yield time series.
dividend_yield_annual: Calendar year dividend yield time series.
dividends_annual: Calendar year dividends.
dividend_paying_years: Number of years of consecutive dividend payments.
dividend_growing_years: Number of years when the annual dividend was growing.
get_dividend_mean_yield: Arithmetic mean for annual dividend yield.

Examples

>>> x = ok.AssetList(['T.US', 'XOM.US'], first_date='1984-01', last_date='1994-12')
>>> x.get_dividend_mean_growth_rate(period=3)
T.US      0.020067
XOM.US    0.024281
dtype: float64

get_dividend_mean_yield(period=5)

Calculate the arithmetic mean for annual dividend yield (LTM) over a specified period.

Dividend yield is taken for full calendar annual dividends.

Parameters:

periodint, default 5: Mean dividend yield trailing period in years. Period should be a positive integer and not exceed the available data period_length.

Returns:

Series: Mean dividend yield value for each asset.

See also

dividend_yield: Dividend yield time series.
dividend_yield_annual: Calendar year dividend yield time series.
dividends_annual: Calendar year dividends.
get_dividend_mean_growth_rate: Geometric mean of annual dividends growth rate.
dividend_paying_years: Number of years of consecutive dividend payments.
dividend_growing_years: Number of years when the annual dividend was growing.

Examples

>>> al = ok.AssetList(["SBERP.MOEX", "LKOH.MOEX"], ccy='RUB', first_date='2005-01', last_date='2023-12')
>>> al.get_dividend_mean_yield(period=3)
SBERP.MOEX    0.052987
LKOH.MOEX     0.156526
dtype: float64

tracking_difference(rolling_window=None)

Return tracking difference for the rate of return of assets.

Tracking difference is calculated by measuring the accumulated difference between the returns of a benchmark and those of the ETF replicating it (could be mutual funds, or other types of assets). Tracking difference is measured in percents.

Benchmark should be in the first position of the symbols list in AssetList parameters.

Parameters:

rolling_windowint or None, default None: Size of the moving window in months. If None calculate expanding tracking difference.

Returns:

DataFrame: Tracking diffirence time series for each asset.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SP500TR.INDX', 'SPY.US', 'VOO.US'], last_date='2021-01')
>>> x.tracking_difference().plot()
>>> plt.show()

To calculate rolling Tracking difference set rolling_window to a number of months (moving window size):

>>> x.tracking_difference(rolling_window = 24).plot()
>>> plt.show()

tracking_difference_annualized(rolling_window=None)

Calculate annualized tracking difference time series for the rate of return of assets.

Tracking difference is calculated by measuring the accumulated difference between the returns of a benchmark and ETFs replicating it (could be mutual funds, or other types of assets). Tracking difference is measured in percents.

Benchmark should be in the first position of the symbols list in AssetList parameters.

Annual values are available for history periods of more than 12 months. Returns for less than 12 months can’t be annualized According to the CFA Institute’s Global Investment Performance Standards (GIPS).

Parameters:

rolling_windowint or None, default None: Size of the moving window in months. Must be at least 12 months. If None calculate expanding annualized tracking difference.

Returns:

DataFrame: Annualized tracking diffirence time series for each asset.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SP500TR.INDX', 'SPY.US', 'VOO.US'], last_date='2021-01')
>>> x.tracking_difference_annualized().plot()

To calculate rolling annualized tracking difference set rolling_window to a number of months (moving window size):

>>> x.tracking_difference_annualized(rolling_window = 12*5).plot()
>>> plt.show()

property tracking_difference_annual

Calculate tracking difference for each calendar year.

Tracking difference is calculated by measuring the accumulated difference between the returns of a benchmark and ETFs replicating it (could be mutual funds, or other types of assets). Tracking difference is measured in percents.

Benchmark should be in the first position of the symbols list in AssetList parameters.

Returns:

DataFrame: Time series with tracking difference for each calendar year period.

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['SP500TR.INDX', 'VOO.US', 'SPXS.LSE'], inflation=False)
>>> al.tracking_difference_annual.plot(kind='bar')

tracking_error(rolling_window=None)

Calculate tracking error time series for the rate of return of assets.

Tracking error is defined as the standard deviation of the difference between the returns of the asset and the returns of the benchmark. Tracking error is measured in percents.

Benchmark should be in the first position of the symbols list in AssetList parameters.

Parameters:

rolling_windowint or None, default None: Size of the moving window in months. Must be at least 12 months. If None calculate expanding tracking error.

Returns:

DataFrame: rolling or expanding tracking error time series for each asset.

Examples

>>> import matplotlib.pyplot as plt
>>> x = ok.AssetList(['SP500TR.INDX', 'SPY.US', 'VOO.US'], last_date='2021-01')
>>> x.tracking_error().plot()
>>> plt.show()

To calculate rolling tracking error set rolling_window to a number of months (moving window size):

>>> x.tracking_error(rolling_window = 12*5).plot()
>>> plt.show()

index_corr(rolling_window=None)

Compute correlation with the index (or benchmark) time series for the assets. Expanding or rolling correlation is available.

Index (benchmark) should be in the first position of the symbols list in AssetList parameters. There should be at least 12 months of historical data.

Parameters:

rolling_windowint or None, default None: Size of the moving window in months. Must be at least 12 months. If None calculate expanding correlation with index.

Returns:

DataFrame: Rolling or expanding correlation with the index (or benchmark) time series for each asset.

Examples

>>> import matplotlib.pyplot as plt
>>> sp = ok.AssetList(['SP500TR.INDX', 'VBMFX.US', 'GC.COMM'])
>>> sp.names
{'SP500TR.INDX': 'S&P 500 (TR)',
'VBMFX.US': 'VANGUARD TOTAL BOND MARKET INDEX FUND INVESTOR SHARES',
'GC.COMM': 'Gold'}
>>> sp.index_corr().plot()  # expanding correlation with S&P 500
>>> plt.show()

To calculate rolling correlation with S&P 500 set rolling_window to a number of months (moving window size):

>>> sp.index_corr(rolling_window=24).plot()
>>> plt.show()

index_beta(rolling_window=None)

Compute beta coefficient time series for the assets.

Beta coefficient is defined in Capital Asset Pricing Model (CAPM). It is a measure of how an individual asset moves (on average) when the benchmark increases or decreases. When beta is positive, the asset price tends to move in the same direction as the benchmark, and the magnitude of beta tells by how much.

Index (benchmark) should be in the first position of the symbols list in AssetList parameters. There should be at least 12 months of historical data.

Parameters:

rolling_windowint or None, default None: Size of the moving window in months. Must be at least 12 months. If None calculate expanding beta coefficient.

Returns:

DataFrame: rollinf or expanding beta coefficient time series for each asset.

See also

index_corr: Compute correlation with the index (or benchmark).
index_rolling_corr: Compute rolling correlation with the index (or benchmark).
index_beta: Compute beta coefficient.

Examples

>>> import matplotlib.pyplot as plt
>>> sp = ok.AssetList(['SP500TR.INDX', 'VBMFX.US', 'GC.COMM', 'VNQ.US'])
>>> sp.names
{'SP500TR.INDX': 'S&P 500 (TR)',
'VBMFX.US': 'VANGUARD TOTAL BOND MARKET INDEX FUND INVESTOR SHARES',
'GC.COMM': 'Gold',
'VNQ.US': 'Vanguard Real Estate Index Fund ETF Shares'}
>>> sp.index_beta().plot()
>>> plt.show()

To calculate rolling beta set rolling_window to a number of months (moving window size):

>>> sp.index_beta(rolling_window = 12 * 5).plot()  # 5 years moving window
>>> plt.show()

property skewness

Compute expanding skewness of the return time series for each asset returns.

Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean. The skewness value can be positive, zero, negative, or undefined.

For normally distributed returns, the skewness should be about zero. A skewness value greater than zero means that there is more weight in the right tail of the distribution.

Returns:

Dataframe: Expanding skewness time series for each asset.

See also

skewness_rolling: Compute rolling skewness.
kurtosis: Calculate expanding Fisher (normalized) kurtosis.
kurtosis_rolling: Calculate rolling Fisher (normalized) kurtosis.
jarque_bera: Perform Jarque-Bera test for normality.
kstest: Perform Kolmogorov-Smirnov test for different types of distributions.

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['VFINX.US', 'GC.COMM'], last_date='2021-01')
>>> al.names
{'VFINX.US': 'VANGUARD 500 INDEX FUND INVESTOR SHARES',
'GC.COMM': 'Gold'}
>>> al.skewness.plot()
>>> plt.show()

skewness_rolling(window=60)

Compute rolling skewness of the return time series for each asset.

Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean. The skewness value can be positive, zero, negative, or undefined.

For normally distributed returns, the skewness should be about zero. A skewness value greater than zero means that there is more weight in the right tail of the distribution.

Parameters:

windowint, default 60: Rolling window size in months. This is the number of observations used for calculating the statistic. The window size should be at least 12 months.

Returns:

DataFrame: Rolling skewness time series for each asset.

See also

skewness: Compute skewness.
kurtosis: Calculate expanding Fisher (normalized) kurtosis.
kurtosis_rolling: Calculate rolling Fisher (normalized) kurtosis.
jarque_bera: Perform Jarque-Bera test for normality.
kstest: Perform Kolmogorov-Smirnov test for different types of distributions.

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['VFINX.US', 'GC.COMM'], last_date='2021-01')
>>> al.names
{'VFINX.US': 'VANGUARD 500 INDEX FUND INVESTOR SHARES',
'GC.COMM': 'Gold'}
>>> al.skewness_rolling(window=12*5).plot()
>>> plt.show()

property kurtosis

Calculate expanding Fisher (normalized) kurtosis of the return time series for each asset.

Kurtosis is the fourth central moment divided by the square of the variance. It is a measure of the “tailedness” of the probability distribution of a real-valued random variable.

Kurtosis should be close to zero for normal distribution.

Returns:

DataFrame: Expanding kurtosis time series for each asset.

See also

skewness: Compute skewness.
skewness_rolling: Compute rolling skewness.
kurtosis_rolling: Calculate rolling Fisher (normalized) kurtosis.
jarque_bera: Perform Jarque-Bera test for normality.
kstest: Perform Kolmogorov-Smirnov test for different types of distributions.

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['GC.COMM', 'FNER.INDX'], first_date='2000-01', last_date='2021-01')
>>> al.names
{'GC.COMM': 'Gold',
'FNER.INDX': 'FTSE NAREIT All Equity REITs'}
>>> al.kurtosis.plot()
>>> plt.show()

kurtosis_rolling(window=60)

Calculate rolling Fisher (normalized) kurtosis of the return time series for each asset.

Kurtosis is the fourth central moment divided by the square of the variance. It is a measure of the “tailedness” of the probability distribution of a real-valued random variable.

Kurtosis should be close to zero for normal distribution.

Parameters:

windowint, default 60: Rolling window size in months. This is the number of observations used for calculating the statistic. The window size should be at least 12 months.

Returns:

DataFrame: Rolling kurtosis time series for each asset.

See also

skewness: Compute skewness.
skewness_rolling: Compute rolling skewness.
kurtosis: Calculate expanding Fisher (normalized) kurtosis.
jarque_bera: Perform Jarque-Bera test for normality.
kstest: Perform Kolmogorov-Smirnov test for different types of distributions.

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['GC.COMM', 'FNER.INDX'], first_date='2000-01', last_date='2021-01')
>>> al.names
{'GC.COMM': 'Gold',
'FNER.INDX': 'FTSE NAREIT All Equity REITs'}
>>> al.kurtosis_rolling(window=12*5).plot()
>>> plt.show()

property jarque_bera

Perform Jarque-Bera test for normality of assets returns historical data.

Jarque-Bera test shows whether the returns have the skewness and kurtosis matching a normal distribution (null hypothesis or H0).

Returns:

DataFrame: Returns test statistic and the p-value for the hypothesis test. large Jarque-Bera statistics and tiny p-value indicate that null hypothesis (H0) is rejected and the time series are not normally distributed. Low statistic numbers correspond to normal distribution.

See also

skewness: Compute skewness.
skewness_rolling: Compute rolling skewness.
kurtosis: Calculate expanding Fisher (normalized) kurtosis.
kurtosis_rolling: Calculate rolling Fisher (normalized) kurtosis.
kstest: Perform Kolmogorov-Smirnov test for different types of distributions.

Examples

>>> al = ok.AssetList(['GC.COMM', 'FNER.INDX'], first_date='2000-01', last_date='2021-01')
>>> al.names
{'GC.COMM': 'Gold',
'FNER.INDX': 'FTSE NAREIT All Equity REITs'}
>>> al.jarque_bera
            GC.COMM   FNER.INDX
statistic  4.507287  593.633047
p-value    0.105016    0.000000

Gold return time series (GC.COMM) distribution have small p-values (H0 is not rejected). Null hypothesis (H0) is rejected for FTSE NAREIT Index (FNER.INDX) as Jarque-Bera test shows very small p-value and large statistic.

kstest(distr='norm')

Perform Kolmogorov-Smirnov test for goodness of fit the asset returns to a given distribution.

Kolmogorov-Smirnov is a test of the distribution of assets returns historical data against a given distribution. Under the null hypothesis (H0), the two distributions are identical.

Parameters:

distr{‘norm’, ‘lognorm’}, default ‘norm’: Type of distributions. Can be ‘norm’ - for normal distribution or ‘lognorm’ - for lognormal distribtion.

Returns:

DataFrame: Returns test statistic and the p-value for the hypothesis test. Large test statistics and tiny p-value indicate that null hypothesis (H0) is rejected.

Examples

>>> al = ok.AssetList(['EDV.US'], last_date='2021-01')
>>> al.kstest(distr='lognorm')
             EDV.US
p-value    0.402179
statistic  0.070246

H0 is not rejected for EDV ETF and it seems to have lognormal distribution.

get_sharpe_ratio(rf_return=0)

Calculate Sharpe ratio for the assets.

The Sharpe ratio is the average annual return in excess of the risk-free rate per unit of risk (annualized standard deviation).

Risk-free rate should be taken according to the AssetList base currency.

Parameters:

rf_returnfloat, default 0: Risk-free rate of return.

Returns:

pd.Series

Examples

>>> al = ok.AssetList(['VOO.US', 'BND.US'])
>>> al.get_sharpe_ratio(rf_return=0.02)
VOO.US    0.962619
BND.US    0.390814
dtype: float64

get_sortino_ratio(t_return=0)

Calculate Sortino ratio for the assets with specified target return.

Sortion ratio measures the risk-adjusted return of each asset. It is a modification of the Sharpe ratio but penalizes only those returns falling below a specified target rate of return, while the Sharpe ratio penalizes both upside and downside volatility equally.

Parameters:

t_returnfloat, default 0: Traget rate of return.

Returns:

pd.Series

Examples

>>> al = ok.AssetList(['VOO.US', 'BND.US'], last_date='2021-12')
>>> al.get_sortino_ratio(t_return=0.03)
VOO.US    1.321951
BND.US    0.028969
dtype: float64

property currency

Return the base currency of the Asset List.

Such properties as rate of return and risk are adjusted to the base currency.

Returns:

okama.Asset: Base currency of the Asset List in form of okama.Asset class.

plot_assets(kind='mean', tickers='tickers', pct_values=False, xy_text=(0, 10))

Plot the assets points on the risk-return chart with annotations.

Annualized values for risk and return are used. Risk is a standard deviation of monthly rate of return time series. Return can be an annualized mean return (expected return) or CAGR (Compound annual growth rate).

Parameters:

kind{‘mean’, ‘cagr’}, default ‘mean’: Type of Return: annualized mean return (expected return) or CAGR (Compound annual growth rate).
tickers{‘tickers’, ‘names’} or list of str, default ‘tickers’: Annotation type for assets. ‘tickers’ - assets symbols are shown in form of ‘SPY.US’ ‘names’ - assets names are used like - ‘SPDR S&P 500 ETF Trust’ To show custom annotations for each asset pass the list of names.
pct_valuesbool, default False: Risk and return values in the axes: Algebraic annotation (False) Percents (True)
xy_texttuple, default (0, 10): The shift of the annotation text (x, y) from the point.

Returns:

Axes‘matplotlib.axes._subplots.AxesSubplot’

Examples

>>> import matplotlib.pyplot as plt
>>> al = ok.AssetList(['SPY.US', 'AGG.US'], ccy='USD', inflation=False)
>>> al.plot_assets()
>>> plt.show()

Plotting with default parameters values shows expected return, ticker annotations and algebraic values for risk and return. To use CAGR instead of expected return use kind=’cagr’.

>>> al.plot_assets(kind='cagr',
...               tickers=['US Stocks', 'US Bonds'],  # use custom annotations for the assets
...               pct_values=True  # risk and return values are in percents
...               )
>>> plt.show()

property symbols

Return a list of financial symbols used to set the AssetList.

Symbols are similar to tickers but have a namespace information:

SPY.US is a symbol
SPY is a ticker

Returns:

list of str: List of symbols included in the Asset List.

property tickers

Return a list of tickers (symbols without a namespace) used to set the AssetList.

tickers are similar to symbols but do not have namespace information:

SPY is a ticker
SPY.US is a symbol

Returns:

list of str: List of tickers included in the Asset List.