OpenSeries
OpenSeries is a project with tools to perform timeseries analysis on a single
asset or a group of assets. It is solely made for daily or less frequent data.
Changelog
Basic Usage
To install:
pip install openseries
An overview of an OpenTimeSeries object is shown in the below example. Most of the
time an object will be constructed from the constructing class methods. The
OpenTimeSeries and OpenFrame classes are both subclasses of
the Pydantic BaseModel.
To make use of some tools available in the Pandas library
the OpenTimeSeries
and OpenFrame
classes have an attribute tsdf
which is a DataFrame constructed from the raw data in the lists dates
and values
.
from pandas import DataFrame, DatetimeIndex
from openseries.series import OpenTimeSeries, ValueType
series = OpenTimeSeries(
timeseriesId="",
instrumentId="",
currency="SEK",
dates=["2020-09-03", "2020-09-04", "2020-09-07", "2020-09-08", "2020-09-09"],
name="Timeseries",
label="Timeseries",
valuetype=ValueType.PRICE,
values=[114.9965, 114.8355, 114.8694, 115.1131, 114.8643],
local_ccy=True,
tsdf=DataFrame(
data=[114.9965, 114.8355, 114.8694, 115.1131, 114.8643],
index=[
d.date()
for d in DatetimeIndex(
[
"2020-09-03",
"2020-09-04",
"2020-09-07",
"2020-09-08",
"2020-09-09",
]
)
],
columns=[["Timeseries"], [ValueType.PRICE]],
dtype="float64",
),
)
Sample output using the OpenFrame.all_properties() method:
Scilla Global Equity C (simulation+fund) Global Low Volatility index, SEK
ValueType.PRICE ValueType.PRICE
observations 4309 4309
Max drawdown in cal yr -0.309849 -0.348681
Total return 3.641282 1.946319
last indices 2023-04-05 2023-04-05
Worst -0.071616 -0.089415
first indices 2006-01-03 2006-01-03
Downside deviation 0.085956 0.086723
Sortino ratio 1.119993 0.802975
VaR 95.0% -0.011365 -0.010807
Imp vol from VaR 95% 0.109204 0.103834
Arithmetic return 0.096271 0.069636
Kurtosis 8.511166 17.527367
Volatility 0.120279 0.117866
Max drawdown -0.309849 -0.435444
Max drawdown dates 2020-03-23 2009-03-09
span of days 6301 6301
Geometric return 0.093057 0.06464
Positive share 0.541783 0.551996
CVaR 95.0% -0.01793 -0.018429
Worst month -0.122503 -0.154485
Z-score 0.587905 0.103241
Return vol ratio 0.800396 0.59081
Skew -0.650782 -0.888109
Usage example on Jupyter Nbviewer and Mybinder.org
Development Instructions
These instructions assume that you
have a compatible Python version installed on your machine and that you are OK
to install this project in a virtual environment. If not, feel free to do it your
own way.
Windows Powershell
git clone https://github.com/CaptorAB/OpenSeries.git
cd OpenSeries
./make.ps1 -task make
Mac Terminal/Linux
git clone https://github.com/CaptorAB/OpenSeries.git
cd OpenSeries
make
source source_me
make install
Testing and Linting / Type-checking
Flake8, Black and Pylint checking is embedded in the pre-commit hook but not mypy. All
packages except Black are used in the project's GitHub workflows and are run when the
lint
alternative is chosen in the below commands.
The silenced error codes can be found in the
pyproject.toml
files
Windows Powershell
./make.ps1 -task test
./make.ps1 -task lint
Mac Terminal/Linux
make test
make lint
Table of Contents
Files in the project
File |
Description |
series.py |
Defines the class OpenTimeSeries for managing and analyzing a single timeseries. The module also defines a function timeseries_chain that can be used to chain two timeseries objects together. |
frame.py |
Defines the class OpenFrame for managing a group of timeseries, and e.g. calculate a portfolio timeseries from a rebalancing strategy between timeseries. |
datefixer.py |
Date utilities. Please read the docstring of each function for its description. |
plotly_layouts.json |
Plotly defaults used in the plot_bars and plot_series methods. |
plotly_captor_logo.json |
JSON with a link to the Captor logo used in the plot_bars and plot_series methods. |
risk.py |
Methods used to calculate VaR, CVaR and drawdowns. |
sim_price.py |
Simulates OpenTimeSeries from different stochastic processes. |
stoch_processes.py |
Generates stochastic processes used in the sim_price.py module. |
types.py |
Contains all bespoke typing. |
Class methods used to construct an OpenTimeSeries object.
Method |
Applies to |
Description |
from_df |
OpenTimeSeries |
Class method to create an OpenTimeSeries object from a pandas.DataFrame column. |
from_fixed_rate |
OpenTimeSeries |
Class method to create an OpenTimeSeries object from a fixed rate, number of days and an end date. |
parse_obj |
OpenTimeSeries |
A method inherited from the Pydantic BaseModel to construct an object from a dict . |
from_deepcopy |
OpenTimeSeries , OpenFrame |
Creates a copy of an OpenTimeSeries object. |
Non-numeric or "helper" properties that apply only to the OpenTimeSeries class.
Property |
type |
Applies to |
Description |
timeseriesId |
str |
OpenTimeSeries |
Placeholder for database identifier for the timeseries. Can be left as empty string. |
instrumentId |
str |
OpenTimeSeries |
Placeholder for database identifier for the instrument associated with the timeseries. Can be left as empty string. |
dates |
List[str] |
OpenTimeSeries |
Dates of the timeseries. Not edited by any method to allow reversion to original. |
values |
List[float] |
OpenTimeSeries |
Values of the timeseries. Not edited by any method to allow reversion to original. |
currency |
str |
OpenTimeSeries |
Currency of the timeseries. Only used if conversion/hedging methods are added. |
domestic |
str |
OpenTimeSeries |
Domestic currency of the user / investor. Only used if conversion/hedging methods are added. |
local_ccy |
bool |
OpenTimeSeries |
Indicates if series should be in its local currency or the domestic currency of the user. Only used if conversion/hedging methods are added. |
name |
str |
OpenTimeSeries |
An identifier field. |
isin |
str |
OpenTimeSeries |
ISIN code of the associated instrument. If any. |
label |
str |
OpenTimeSeries |
Field used in outputs. Derived from name as default. |
countries |
list or str |
OpenTimeSeries |
(List of) country code(s) according to ISO 3166-1 alpha-2 used to generate business days. |
valuetype |
ValueType |
OpenTimeSeries |
Field identifies the type of values in the series. ValueType is an Enum. |
Non-numeric or "helper" properties that apply only to the OpenFrame class.
Property |
type |
Applies to |
Description |
constituents |
List[OpenTimeSeries] |
OpenFrame |
A list of the OpenTimeSeries that make up an OpenFrame. |
columns_lvl_zero |
list |
OpenFrame |
A list of the level zero column names in the OpenFrame pandas.DataFrame. |
columns_lvl_one |
list |
OpenFrame |
A list of the level one column names in the OpenFrame pandas.DataFrame. |
item_count |
int |
OpenFrame |
Number of columns in the OpenFrame pandas.DataFrame. |
weights |
List[float] |
OpenFrame |
Weights used in the method make_portfolio . |
first_indices |
pandas.Series |
OpenFrame |
First dates of all the series in the OpenFrame. |
last_indices |
pandas.Series |
OpenFrame |
Last dates of all the series in the OpenFrame. |
lengths_of_items |
pandas.Series |
OpenFrame |
Number of items in each of the series in the OpenFrame. |
span_of_days_all |
pandas.Series |
OpenFrame |
Number of days from the first to the last in each of the series. |
Non-numeric or "helper" properties that apply to both the OpenTimeSeries and the OpenFrame class.
Property |
type |
Applies to |
Description |
first_idx |
datetime.date |
OpenTimeSeries , OpenFrame |
First date of the series. |
last_idx |
datetime.date |
OpenTimeSeries , OpenFrame |
Last date of the series. |
length |
int |
OpenTimeSeries , OpenFrame |
Number of items in the series. |
span_of_days |
int |
OpenTimeSeries , OpenFrame |
Number of days from the first to the last date in the series. |
tsdf |
pandas.DataFrame |
OpenTimeSeries , OpenFrame |
The Pandas DataFrame which gets edited by the class methods. |
max_drawdown_date |
datetime.date , pandas.Series |
OpenTimeSeries , OpenFrame |
Date when the maximum drawdown occurred. |
periods_in_a_year |
float |
OpenTimeSeries , OpenFrame |
The number of observations in an average year for all days in the data. |
yearfrac |
float |
OpenTimeSeries , OpenFrame |
Length of timeseries expressed as np.float64 fraction of a year with 365.25 days. |
Methods that apply only to the OpenTimeSeries class.
Method |
Applies to |
Description |
setup_class |
OpenTimeSeries |
Class method that defines the domestic home currency and the countries home countries attributes. |
to_json |
OpenTimeSeries |
Method to export the OpenTimeSeries __dict__ to a json file. |
pandas_df |
OpenTimeSeries |
Method to create the tsdf pandas.DataFrame from the dates and values . |
set_new_label |
OpenTimeSeries |
Method to change the pandas.DataFrame column MultiIndex. |
running_adjustment |
OpenTimeSeries |
Adjusts the series performance with a float factor. |
ewma_vol_func |
OpenTimeSeries |
Returns a pandas.Series with volatility based on Exponentially Weighted Moving Average. |
from_1d_rate_to_cumret |
OpenTimeSeries |
Converts a series of 1-day rates into a cumulative valueseries. |
check_isincode |
OpenTimeSeries |
Pydantic validator method to validate the ISIN code if provided. |
Methods that apply only to the OpenFrame class.
Method |
Applies to |
Description |
merge_series |
OpenFrame |
Merges the Pandas Dataframes of the constituent OpenTimeSeries. |
trunc_frame |
OpenFrame |
Truncates the OpenFrame to a common period. |
add_timeseries |
OpenFrame |
Adds a given OpenTimeSeries to the OpenFrame. |
delete_timeseries |
OpenFrame |
Deletes an OpenTimeSeries from the OpenFrame. |
relative |
OpenFrame |
Calculates a new series that is the relative performance of two others. |
make_portfolio |
OpenFrame |
Calculates a portfolio timeseries from series and weights. |
ord_least_squares_fit |
OpenFrame |
Performs a regression and an Ordinary Least Squares fit. |
beta |
OpenFrame |
Calculates Beta of an asset relative a market. |
jensen_alpha |
OpenFrame |
Calculates Jensen's Alpha of an asset relative a market. |
tracking_error_func |
OpenFrame |
Calculates the tracking errors relative to a selected series in the OpenFrame. |
info_ratio_func |
OpenFrame |
Calculates the information ratios relative to a selected series in the OpenFrame. |
capture_ratio_func |
OpenFrame |
Calculates up, down and up/down capture ratios relative to a selected series. |
rolling_info_ratio |
OpenFrame |
Returns a pandas.DataFrame with the rolling information ratio between two series. |
rolling_beta |
OpenFrame |
Returns a pandas.DataFrame with the rolling Beta of an asset relative a market. |
rolling_corr |
OpenFrame |
Calculates and adds a series of rolling correlations between two other series. |
ewma_risk |
OpenFrame |
Returns a pandas.DataFrame with volatility and correlation based on Exponentially Weighted Moving Average. |
check_labels_unique |
OpenFrame |
Pydantic validator method to validate that each of the passed timeseries must have unique labels. |
Methods that apply to both the OpenTimeSeries and the OpenFrame class.
Method |
Applies to |
Description |
align_index_to_local_cdays |
OpenTimeSeries , OpenFrame |
Aligns the series dates to a business calendar. Defaults to Sweden. |
resample |
OpenTimeSeries , OpenFrame |
Resamples the series to a specific frequency. |
resample_to_business_period_ends |
OpenTimeSeries , OpenFrame |
Resamples the series to month-end dates with monthly, quarterly or annual frequency. |
value_nan_handle |
OpenTimeSeries , OpenFrame |
Fills Nan in a value series with the preceding non-Nan value. |
return_nan_handle |
OpenTimeSeries , OpenFrame |
Replaces Nan in a return series with a 0.0 float . |
to_cumret |
OpenTimeSeries , OpenFrame |
Converts a return series into a value series and/or resets a value series to be rebased from 1.0. |
value_to_ret |
OpenTimeSeries , OpenFrame |
Converts a value series into a percentage return series. |
value_to_diff |
OpenTimeSeries , OpenFrame |
Converts a value series into a series of differences. |
value_to_log |
OpenTimeSeries , OpenFrame |
Converts a value series into a logarithmic return series. |
value_ret_calendar_period |
OpenTimeSeries , OpenFrame |
Returns the series simple return for a specific calendar period. |
plot_series |
OpenTimeSeries , OpenFrame |
Opens a HTML Plotly Scatter plot of the series in a browser window. |
plot_bars |
OpenTimeSeries , OpenFrame |
Opens a HTML Plotly Bar plot of the series in a browser window. |
drawdown_details |
OpenTimeSeries , OpenFrame |
Returns detailed drawdown characteristics. |
to_drawdown_series |
OpenTimeSeries , OpenFrame |
Converts the series into drawdown series. |
rolling_return |
OpenTimeSeries , OpenFrame |
Returns a pandas.DataFrame with rolling returns. |
rolling_vol |
OpenTimeSeries , OpenFrame |
Returns a pandas.DataFrame with rolling volatilities. |
rolling_var_down |
OpenTimeSeries , OpenFrame |
Returns a pandas.DataFrame with rolling VaR figures. |
rolling_cvar_down |
OpenTimeSeries , OpenFrame |
Returns a pandas.DataFrame with rolling CVaR figures. |
calc_range |
OpenTimeSeries , OpenFrame |
Returns the start and end dates of a range from specific period definitions. Used by the below numeric methods and not meant to be used independently. |
Numeric properties available for individual OpenTimeSeries or on all series in an OpenFrame.
Property |
type |
Applies to |
Description |
all_properties |
pandas.DataFrame |
OpenTimeSeries , OpenFrame |
Returns most of the properties in one go. |
arithmetic_ret |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Annualized arithmetic mean of returns. |
geo_ret |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Compound Annual Growth Rate(CAGR), a specific implementation of geometric mean. |
value_ret |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Simple return from first to last observation. |
vol |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Annualized volatility. Pandas .std() is the equivalent of stdev.s([...]) in MS excel. |
downside_deviation |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Downside deviation is the volatility of all negative return observations. Minimum Accepted Return (MAR) set to zero. |
ret_vol_ratio |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Ratio of arithmetic mean return and annualized volatility. It is the Sharpe Ratio with the riskfree rate set to zero. |
sortino_ratio |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
The Sortino Ratio is the arithmetic mean return divided by the downside deviation. This attribute assumes that the riskfree rate and the MAR are both zero. |
var_down |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Downside 95% Value At Risk, "VaR". The equivalent of percentile.inc([...], 1-level) over returns in MS Excel. For other confidence levels use the corresponding method. |
cvar_down |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Downside 95% Conditional Value At Risk, "CVaR". For other confidence levels use the corresponding method. |
worst |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Most negative percentage change of a single observation. |
worst_month |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Most negative month. |
max_drawdown |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Maximum drawdown. |
max_drawdown_cal_year |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Max drawdown in a single calendar year. |
positive_share |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
The share of percentage changes that are positive. |
vol_from_var |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Implied annualized volatility from the Downside VaR using the assumption that returns are normally distributed. |
skew |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Skew of the return distribution. |
kurtosis |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Kurtosis of the return distribution. |
z_score |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Z-score as (last return - mean return) / standard deviation of returns. |
correl_matrix |
pandas.DataFrame |
OpenFrame |
A correlation matrix. |
Methods below are identical to the Numeric Properties above.
They are simply methods that take different date or length inputs to return the
properties for subset periods.
Method |
type |
Applies to |
Description |
arithmetic_ret_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Annualized arithmetic mean of returns. |
geo_ret_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Compound Annual Growth Rate(CAGR), a specific implementation of geometric mean. |
value_ret_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Simple return from first to last observation. |
vol_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Annualized volatility. Pandas .std() is the equivalent of stdev.s([...]) in MS excel. |
downside_deviation_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Downside deviation is the volatility of all negative return observations. MAR and riskfree rate can be set. |
ret_vol_ratio_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Ratio of arithmetic mean return and annualized volatility. It is the Sharpe Ratio with the riskfree rate set to zero. A riskfree rate can be set as a float or a series chosen for the frame function. |
sortino_ratio_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
The Sortino Ratio is the arithmetic mean return divided by the downside deviation. A riskfree rate can be set as a float or a series chosen for the frame function. MAR is set to zero. |
var_down_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Downside 95% Value At Risk, "VaR". The equivalent of percentile.inc([...], 1-level) over returns in MS Excel. Default is 95% confidence level. |
cvar_down_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Downside 95% Conditional Value At Risk, "CVaR". Default is 95% confidence level. |
worst_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Most negative percentage change for a given number of observations (default=1). |
max_drawdown_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Maximum drawdown. |
positive_share_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
The share of percentage changes that are positive. |
vol_from_var_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Implied annualized volatility from the Downside VaR using the assumption that returns are normally distributed. |
skew_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Skew of the return distribution. |
kurtosis_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Kurtosis of the return distribution. |
z_score_func |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
Z-score as (last return - mean return) / standard deviation of returns. |
target_weight_from_var |
float , pandas.Series |
OpenTimeSeries , OpenFrame |
A position target weight from the ratio between a VaR implied volatility and a given target volatility. |