Skip to content

accessors moduleΒΆ

Custom pandas accessors for returns data.

Methods can be accessed as follows:

Note

The underlying Series/DataFrame must already be a return series. To convert price to returns, use ReturnsAccessor.from_value().

Grouping is only supported by the methods that accept the group_by argument.

Accessors do not utilize caching.

There are three options to compute returns and get the accessor:

>>> import numpy as np
>>> import pandas as pd
>>> import vectorbt as vbt

>>> price = pd.Series([1.1, 1.2, 1.3, 1.2, 1.1])

>>> # 1. pd.Series.pct_change
>>> rets = price.pct_change()
>>> ret_acc = rets.vbt.returns(freq='d')

>>> # 2. vectorbt.generic.accessors.GenericAccessor.to_returns
>>> rets = price.vbt.to_returns()
>>> ret_acc = rets.vbt.returns(freq='d')

>>> # 3. vectorbt.returns.accessors.ReturnsAccessor.from_value
>>> ret_acc = pd.Series.vbt.returns.from_value(price, freq='d')

>>> # vectorbt.returns.accessors.ReturnsAccessor.total
>>> ret_acc.total()
0.0

The accessors extend vectorbt.generic.accessors.

>>> # inherited from GenericAccessor
>>> ret_acc.max()
0.09090909090909083

VectorBT PRO

See the rolling metrics examples for optimized calculations of rolling Sharpe ratios and other return statistics.

DefaultsΒΆ

ReturnsAccessor accepts defaults dictionary where you can pass defaults for arguments used throughout the accessor, such as

  • start_value: The starting value.
  • window: Window length.
  • minp: Minimum number of observations in a window required to have a value.
  • ddof: Delta Degrees of Freedom.
  • risk_free: Constant risk-free return throughout the period.
  • levy_alpha: Scaling relation (Levy stability exponent).
  • required_return: Minimum acceptance return of the investor.
  • cutoff: Decimal representing the percentage cutoff for the bottom percentile of returns.

StatsΒΆ

>>> ret_acc.stats()
UserWarning: Metric 'benchmark_return' requires benchmark_rets to be set
UserWarning: Metric 'alpha' requires benchmark_rets to be set
UserWarning: Metric 'beta' requires benchmark_rets to be set

Start                                      0
End                                        4
Duration                     5 days 00:00:00
Total Return [%]                           0
Annualized Return [%]                      0
Annualized Volatility [%]            184.643
Sharpe Ratio                        0.691185
Calmar Ratio                               0
Max Drawdown [%]                     15.3846
Omega Ratio                          1.08727
Sortino Ratio                        1.17805
Skew                              0.00151002
Kurtosis                            -5.94737
Tail Ratio                           1.08985
Common Sense Ratio                   1.08985
Value at Risk                     -0.0823718
dtype: object

The missing benchmark_rets can be either passed to the contrustor of the accessor or as a setting to StatsBuilderMixin.stats():

>>> benchmark = pd.Series([1.05, 1.1, 1.15, 1.1, 1.05])
>>> benchmark_rets = benchmark.vbt.to_returns()

>>> ret_acc.stats(settings=dict(benchmark_rets=benchmark_rets))
Start                                      0
End                                        4
Duration                     5 days 00:00:00
Total Return [%]                           0
Benchmark Return [%]                       0
Annualized Return [%]                      0
Annualized Volatility [%]            184.643
Sharpe Ratio                        0.691185
Calmar Ratio                               0
Max Drawdown [%]                     15.3846
Omega Ratio                          1.08727
Sortino Ratio                        1.17805
Skew                              0.00151002
Kurtosis                            -5.94737
Tail Ratio                           1.08985
Common Sense Ratio                   1.08985
Value at Risk                     -0.0823718
Alpha                                0.78789
Beta                                 1.83864
dtype: object

Note

StatsBuilderMixin.stats() does not support grouping.

PlotsΒΆ

This class inherits subplots from GenericAccessor.


ReturnsAccessor classΒΆ

ReturnsAccessor(
    obj,
    benchmark_rets=None,
    year_freq=None,
    defaults=None,
    **kwargs
)

Accessor on top of return series. For both, Series and DataFrames.

Accessible through pd.Series.vbt.returns and pd.DataFrame.vbt.returns.

Args

obj : pd.Series or pd.DataFrame
Pandas object representing returns.
benchmark_rets : array_like
Pandas object representing benchmark returns.
year_freq : any
Year frequency for annualization purposes.
defaults : dict
Defaults that override returns.defaults in settings.
**kwargs
Keyword arguments that are passed down to GenericAccessor.

Superclasses

Inherited members

Subclasses


alpha methodΒΆ

ReturnsAccessor.alpha(
    benchmark_rets=None,
    risk_free=None,
    engine=None,
    wrap_kwargs=None
)

See alpha().


ann_factor propertyΒΆ

Get annualization factor.


annual methodΒΆ

ReturnsAccessor.annual(
    engine=None,
    **kwargs
)

Annual returns.


annualized methodΒΆ

ReturnsAccessor.annualized(
    engine=None,
    wrap_kwargs=None
)

See annualized_return().


annualized_volatility methodΒΆ

ReturnsAccessor.annualized_volatility(
    levy_alpha=None,
    ddof=None,
    engine=None,
    wrap_kwargs=None
)

See annualized_volatility().


benchmark_rets propertyΒΆ

Benchmark returns.


beta methodΒΆ

ReturnsAccessor.beta(
    benchmark_rets=None,
    engine=None,
    wrap_kwargs=None
)

See beta().


calmar_ratio methodΒΆ

ReturnsAccessor.calmar_ratio(
    engine=None,
    wrap_kwargs=None
)

See calmar_ratio().


capture methodΒΆ

ReturnsAccessor.capture(
    benchmark_rets=None,
    engine=None,
    wrap_kwargs=None
)

See capture().


common_sense_ratio methodΒΆ

ReturnsAccessor.common_sense_ratio(
    engine=None,
    wrap_kwargs=None
)

Common Sense Ratio.


cond_value_at_risk methodΒΆ

ReturnsAccessor.cond_value_at_risk(
    cutoff=None,
    engine=None,
    wrap_kwargs=None
)

See cond_value_at_risk().


cumulative methodΒΆ

ReturnsAccessor.cumulative(
    start_value=None,
    engine=None,
    wrap_kwargs=None
)

See cum_returns().


daily methodΒΆ

ReturnsAccessor.daily(
    engine=None,
    **kwargs
)

Daily returns.


defaults propertyΒΆ

Defaults for ReturnsAccessor.

Merges returns.defaults from settings with defaults from ReturnsAccessor.


deflated_sharpe_ratio methodΒΆ

ReturnsAccessor.deflated_sharpe_ratio(
    risk_free=None,
    ddof=None,
    var_sharpe=None,
    nb_trials=None,
    bias=True,
    wrap_kwargs=None
)

Deflated Sharpe Ratio (DSR).

Expresses the chance that the advertised strategy has a positive Sharpe ratio.

If var_sharpe is None, is calculated based on all columns. If nb_trials is None, is set to the number of columns.


down_capture methodΒΆ

ReturnsAccessor.down_capture(
    benchmark_rets=None,
    engine=None,
    wrap_kwargs=None
)

See down_capture().


downside_risk methodΒΆ

ReturnsAccessor.downside_risk(
    required_return=None,
    engine=None,
    wrap_kwargs=None
)

See downside_risk().


drawdown methodΒΆ

ReturnsAccessor.drawdown(
    engine=None,
    wrap_kwargs=None
)

Relative decline from a peak.


drawdowns propertyΒΆ

ReturnsAccessor.get_drawdowns() with default arguments.


from_value class methodΒΆ

ReturnsAccessor.from_value(
    value,
    init_value=nan,
    broadcast_kwargs=None,
    engine=None,
    wrap_kwargs=None,
    **kwargs
)

Returns a new ReturnsAccessor instance with returns calculated from value.


get_drawdowns methodΒΆ

ReturnsAccessor.get_drawdowns(
    wrapper_kwargs=None,
    engine=None,
    **kwargs
)

Generate drawdown records of cumulative returns.

See Drawdowns.


indexing_func methodΒΆ

ReturnsAccessor.indexing_func(
    pd_indexing_func,
    **kwargs
)

Perform indexing on ReturnsAccessor.


information_ratio methodΒΆ

ReturnsAccessor.information_ratio(
    benchmark_rets=None,
    ddof=None,
    engine=None,
    wrap_kwargs=None
)

See information_ratio().


max_drawdown methodΒΆ

ReturnsAccessor.max_drawdown(
    engine=None,
    wrap_kwargs=None
)

See max_drawdown().

Yields the same result as max_drawdown of ReturnsAccessor.drawdowns.


metrics class variableΒΆ

Metrics supported by ReturnsAccessor.

Config({
    "start": {
        "title": "Start",
        "calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bf9c0>",
        "agg_func": null,
        "check_is_not_grouped": false,
        "tags": "wrapper"
    },
    "end": {
        "title": "End",
        "calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfa60>",
        "agg_func": null,
        "check_is_not_grouped": false,
        "tags": "wrapper"
    },
    "period": {
        "title": "Period",
        "calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfb00>",
        "apply_to_timedelta": true,
        "agg_func": null,
        "check_is_not_grouped": false,
        "tags": "wrapper"
    },
    "total_return": {
        "title": "Total Return [%]",
        "calc_func": "total",
        "post_calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfba0>",
        "tags": "returns"
    },
    "benchmark_return": {
        "title": "Benchmark Return [%]",
        "calc_func": "benchmark_rets.vbt.returns.total",
        "post_calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfc40>",
        "check_has_benchmark_rets": true,
        "tags": "returns"
    },
    "ann_return": {
        "title": "Annualized Return [%]",
        "calc_func": "annualized",
        "post_calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfce0>",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "ann_volatility": {
        "title": "Annualized Volatility [%]",
        "calc_func": "annualized_volatility",
        "post_calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfd80>",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "max_dd": {
        "title": "Max Drawdown [%]",
        "calc_func": "drawdowns.max_drawdown",
        "post_calc_func": "<function ReturnsAccessor.<lambda> at 0x7f64e09bfe20>",
        "tags": [
            "returns",
            "drawdowns"
        ]
    },
    "max_dd_duration": {
        "title": "Max Drawdown Duration",
        "calc_func": "drawdowns.max_duration",
        "fill_wrap_kwargs": true,
        "tags": [
            "returns",
            "drawdowns",
            "duration"
        ]
    },
    "sharpe_ratio": {
        "title": "Sharpe Ratio",
        "calc_func": "sharpe_ratio",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "calmar_ratio": {
        "title": "Calmar Ratio",
        "calc_func": "calmar_ratio",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "omega_ratio": {
        "title": "Omega Ratio",
        "calc_func": "omega_ratio",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "sortino_ratio": {
        "title": "Sortino Ratio",
        "calc_func": "sortino_ratio",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "skew": {
        "title": "Skew",
        "calc_func": "obj.skew",
        "tags": "returns"
    },
    "kurtosis": {
        "title": "Kurtosis",
        "calc_func": "obj.kurtosis",
        "tags": "returns"
    },
    "tail_ratio": {
        "title": "Tail Ratio",
        "calc_func": "tail_ratio",
        "tags": "returns"
    },
    "common_sense_ratio": {
        "title": "Common Sense Ratio",
        "calc_func": "common_sense_ratio",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "tags": "returns"
    },
    "value_at_risk": {
        "title": "Value at Risk",
        "calc_func": "value_at_risk",
        "tags": "returns"
    },
    "alpha": {
        "title": "Alpha",
        "calc_func": "alpha",
        "check_has_freq": true,
        "check_has_year_freq": true,
        "check_has_benchmark_rets": true,
        "tags": "returns"
    },
    "beta": {
        "title": "Beta",
        "calc_func": "beta",
        "check_has_benchmark_rets": true,
        "tags": "returns"
    }
})

Returns ReturnsAccessor._metrics, which gets (deep) copied upon creation of each instance. Thus, changing this config won't affect the class.

To change metrics, you can either change the config in-place, override this property, or overwrite the instance variable ReturnsAccessor._metrics.


omega_ratio methodΒΆ

ReturnsAccessor.omega_ratio(
    risk_free=None,
    required_return=None,
    engine=None,
    wrap_kwargs=None
)

See omega_ratio().


plots_defaults propertyΒΆ

Defaults for PlotsBuilderMixin.plots().

Merges GenericAccessor.plots_defaults, defaults from ReturnsAccessor.defaults (acting as settings), and returns.plots from settings


qs propertyΒΆ

Quantstats adapter.


resample_total_return methodΒΆ

ReturnsAccessor.resample_total_return(
    freq,
    engine=None,
    wrap_kwargs=None,
    **kwargs
)

Resample returns and calculate total return through engine-neutral dispatch.


resolve_self methodΒΆ

ReturnsAccessor.resolve_self(
    cond_kwargs=None,
    custom_arg_names=None,
    impacts_caching=True,
    silence_warnings=False
)

Resolve self.

See Wrapping.resolve_self().

Creates a copy of this instance year_freq is different in cond_kwargs.


rolling_alpha methodΒΆ

ReturnsAccessor.rolling_alpha(
    benchmark_rets=None,
    window=None,
    minp=None,
    risk_free=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.alpha().


rolling_annualized methodΒΆ

ReturnsAccessor.rolling_annualized(
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.annualized().


rolling_annualized_volatility methodΒΆ

ReturnsAccessor.rolling_annualized_volatility(
    window=None,
    minp=None,
    levy_alpha=None,
    ddof=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.annualized_volatility().


rolling_beta methodΒΆ

ReturnsAccessor.rolling_beta(
    benchmark_rets=None,
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.beta().


rolling_calmar_ratio methodΒΆ

ReturnsAccessor.rolling_calmar_ratio(
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.calmar_ratio().


rolling_capture methodΒΆ

ReturnsAccessor.rolling_capture(
    benchmark_rets=None,
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.capture().


rolling_common_sense_ratio methodΒΆ

ReturnsAccessor.rolling_common_sense_ratio(
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.common_sense_ratio().


rolling_cond_value_at_risk methodΒΆ

ReturnsAccessor.rolling_cond_value_at_risk(
    window=None,
    minp=None,
    cutoff=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.cond_value_at_risk().


rolling_down_capture methodΒΆ

ReturnsAccessor.rolling_down_capture(
    benchmark_rets=None,
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.down_capture().


rolling_downside_risk methodΒΆ

ReturnsAccessor.rolling_downside_risk(
    window=None,
    minp=None,
    required_return=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.downside_risk().


rolling_information_ratio methodΒΆ

ReturnsAccessor.rolling_information_ratio(
    benchmark_rets=None,
    window=None,
    minp=None,
    ddof=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.information_ratio().


rolling_max_drawdown methodΒΆ

ReturnsAccessor.rolling_max_drawdown(
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.max_drawdown().


rolling_omega_ratio methodΒΆ

ReturnsAccessor.rolling_omega_ratio(
    window=None,
    minp=None,
    risk_free=None,
    required_return=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.omega_ratio().


rolling_sharpe_ratio methodΒΆ

ReturnsAccessor.rolling_sharpe_ratio(
    window=None,
    minp=None,
    risk_free=None,
    ddof=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.sharpe_ratio().


rolling_sortino_ratio methodΒΆ

ReturnsAccessor.rolling_sortino_ratio(
    window=None,
    minp=None,
    required_return=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.sortino_ratio().


rolling_tail_ratio methodΒΆ

ReturnsAccessor.rolling_tail_ratio(
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.tail_ratio().


rolling_total methodΒΆ

ReturnsAccessor.rolling_total(
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.total().


rolling_up_capture methodΒΆ

ReturnsAccessor.rolling_up_capture(
    benchmark_rets=None,
    window=None,
    minp=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.up_capture().


rolling_value_at_risk methodΒΆ

ReturnsAccessor.rolling_value_at_risk(
    window=None,
    minp=None,
    cutoff=None,
    engine=None,
    wrap_kwargs=None
)

Rolling version of ReturnsAccessor.value_at_risk().


sharpe_ratio methodΒΆ

ReturnsAccessor.sharpe_ratio(
    risk_free=None,
    ddof=None,
    engine=None,
    wrap_kwargs=None
)

See sharpe_ratio().


sortino_ratio methodΒΆ

ReturnsAccessor.sortino_ratio(
    required_return=None,
    engine=None,
    wrap_kwargs=None
)

See sortino_ratio().


stats_defaults propertyΒΆ

Defaults for StatsBuilderMixin.stats().

Merges GenericAccessor.stats_defaults, defaults from ReturnsAccessor.defaults (acting as settings), and returns.stats from settings


subplots class variableΒΆ

Subplots supported by ReturnsAccessor.

Config({
    "plot": {
        "check_is_not_grouped": true,
        "plot_func": "plot",
        "pass_trace_names": false,
        "tags": "generic"
    }
})

Returns ReturnsAccessor._subplots, which gets (deep) copied upon creation of each instance. Thus, changing this config won't affect the class.

To change subplots, you can either change the config in-place, override this property, or overwrite the instance variable ReturnsAccessor._subplots.


tail_ratio methodΒΆ

ReturnsAccessor.tail_ratio(
    engine=None,
    wrap_kwargs=None
)

See tail_ratio().


total methodΒΆ

ReturnsAccessor.total(
    engine=None,
    wrap_kwargs=None
)

See cum_returns_final().


up_capture methodΒΆ

ReturnsAccessor.up_capture(
    benchmark_rets=None,
    engine=None,
    wrap_kwargs=None
)

See up_capture().


value_at_risk methodΒΆ

ReturnsAccessor.value_at_risk(
    cutoff=None,
    engine=None,
    wrap_kwargs=None
)

See value_at_risk().


year_freq propertyΒΆ

Year frequency for annualization purposes.


ReturnsDFAccessor classΒΆ

ReturnsDFAccessor(
    obj,
    benchmark_rets=None,
    year_freq=None,
    defaults=None,
    **kwargs
)

Accessor on top of return series. For DataFrames only.

Accessible through pd.DataFrame.vbt.returns.

Superclasses

Inherited members


ReturnsSRAccessor classΒΆ

ReturnsSRAccessor(
    obj,
    benchmark_rets=None,
    year_freq=None,
    defaults=None,
    **kwargs
)

Accessor on top of return series. For Series only.

Accessible through pd.Series.vbt.returns.

Superclasses

Inherited members


plot_cumulative methodΒΆ

ReturnsSRAccessor.plot_cumulative(
    benchmark_rets=None,
    start_value=1,
    fill_to_benchmark=False,
    main_kwargs=None,
    benchmark_kwargs=None,
    hline_shape_kwargs=None,
    add_trace_kwargs=None,
    xref='x',
    yref='y',
    fig=None,
    **layout_kwargs
)

Plot cumulative returns.

Args

benchmark_rets : array_like
Benchmark return to compare returns against. Will broadcast per element.
start_value : float
The starting returns.
fill_to_benchmark : bool
Whether to fill between main and benchmark, or between main and start_value.
main_kwargs : dict
Keyword arguments passed to GenericAccessor.plot() for main.
benchmark_kwargs : dict
Keyword arguments passed to GenericAccessor.plot() for benchmark.
hline_shape_kwargs : dict
Keyword arguments passed to plotly.graph_objects.Figure.add_shape for start_value line.
add_trace_kwargs : dict
Keyword arguments passed to add_trace.
xref : str
X coordinate axis.
yref : str
Y coordinate axis.
fig : Figure or FigureWidget
Figure to add traces to.
**layout_kwargs
Keyword arguments for layout.

Usage

>>> import pandas as pd
>>> import numpy as np

>>> np.random.seed(0)
>>> rets = pd.Series(np.random.uniform(-0.05, 0.05, size=100))
>>> benchmark_rets = pd.Series(np.random.uniform(-0.05, 0.05, size=100))
>>> rets.vbt.returns.plot_cumulative(benchmark_rets=benchmark_rets)