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