Utilities

The module empyrical.utils contains various helper functions, e.g. to source risk factor and return data using pandas-datareader and `yfinance.

empyrical.utils.data_path(name)
empyrical.utils.default_returns_func(symbol, start=None, end=None)

Gets returns for a symbol. Queries Yahoo Finance. Attempts to cache SPY.

Parameters
symbolstr

Ticker symbol, e.g. APPL.

startdate, optional

Earliest date to fetch data for. Defaults to earliest date available.

enddate, optional

Latest date to fetch data for. Defaults to latest date available.

Returns
pd.Series
Daily returns for the symbol.
  • See full explanation in tears.create_full_tear_sheet (returns).

empyrical.utils.down(returns, factor_returns, **kwargs)

Calculates a given statistic filtering only negative factor return periods.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returns (optional): float / series

Benchmark return to compare returns against.

function:

the function to run for each rolling window.

(other keywords): other keywords that are required to be passed to the

function in the ‘function’ argument may also be passed in.

Returns
Same as the return of the ‘function’
empyrical.utils.ensure_directory(path)

Ensure that a directory named “path” exists.

empyrical.utils.get_fama_french()

Retrieve Fama-French factors via pandas-datareader Returns ——- pandas.DataFrame

Percent change of Fama-French factors

empyrical.utils.get_returns_cached(filepath, update_func, latest_dt, **kwargs)

Get returns from a cached file if the cache is recent enough, otherwise, try to retrieve via a provided update function and update the cache file. Parameters ———- filepath : str

Path to cached csv file

update_funcfunction

Function to call in case cache is not up-to-date.

latest_dtpd.Timestamp (tz=UTC)

Latest datetime required in csv file.

**kwargsKeyword arguments

Optional keyword arguments will be passed to update_func()

pandas.DataFrame

DataFrame containing returns

empyrical.utils.get_symbol_returns_from_yahoo(symbol, start=None, end=None)

Wrapper for pandas.io.data.get_data_yahoo(). Retrieves prices for symbol from yahoo and computes returns based on adjusted closing prices.

Parameters
symbolstr

Yahoo symbol name to load, e.g. ‘SPY’

startpandas.Timestamp compatible, optional

Start date of time period to retrieve

endpandas.Timestamp compatible, optional

End date of time period to retrieve

Returns
pandas.DataFrame

Returns of symbol in requested period.

empyrical.utils.get_treasury_yield(start=None, end=None, period='3MO')

Load treasury yields from FRED.

Parameters
startdate, optional

Earliest date to fetch data for. Defaults to earliest date available.

enddate, optional

Latest date to fetch data for. Defaults to latest date available.

period{‘1MO’, ‘3MO’, ‘6MO’, 1’, ‘5’, ‘10’}, optional

Which maturity to use.

Returns
——-
pd.Series

Annual treasury yield for every day.

empyrical.utils.get_utc_timestamp(dt)

Returns the Timestamp/DatetimeIndex with either localized or converted to UTC.

Parameters
dtTimestamp/DatetimeIndex

the date(s) to be converted

Returns
same type as input

date(s) converted to UTC

empyrical.utils.load_portfolio_risk_factors(filepath_prefix=None, start=None, end=None)

Load risk factors Mkt-Rf, SMB, HML, Rf, and UMD. Data is stored in HDF5 file. If the data is more than 2 days old, redownload from Dartmouth. Returns ——- five_factors : pd.DataFrame

Risk factors timeseries.

empyrical.utils.roll(*args, **kwargs)

Calculates a given statistic across a rolling time period.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returns (optional): float / series

Benchmark return to compare returns against.

function:

the function to run for each rolling window.

window (keyword): int

the number of periods included in each calculation.

(other keywords): other keywords that are required to be passed to the

function in the ‘function’ argument may also be passed in.

Returns
np.ndarray, pd.Series

depends on input type ndarray(s) ==> ndarray Series(s) ==> pd.Series

A Series or ndarray of the results of the stat across the rolling window.

empyrical.utils.rolling_window(array, length, mutable=False)

Restride an array of shape

(X_0, … X_N)

into an array of shape

(length, X_0 - length + 1, … X_N)

where each slice at index i along the first axis is equivalent to

result[i] = array[length * i:length * (i + 1)]

Parameters
arraynp.ndarray

The base array.

lengthint

Length of the synthetic first axis to generate.

mutablebool, optional

Return a mutable array? The returned array shares the same memory as the input array. This means that writes into the returned array affect array. The returned array also uses strides to map the same values to multiple indices. Writes to a single index may appear to change many values in the returned array.

Returns
outnp.ndarray
empyrical.utils.up(returns, factor_returns, **kwargs)

Calculates a given statistic filtering only positive factor return periods.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returns (optional): float / series

Benchmark return to compare returns against.

function:

the function to run for each rolling window.

(other keywords): other keywords that are required to be passed to the

function in the ‘function’ argument may also be passed in.

Returns
Same as the return of the function