Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

#
drawdowns module

Base class for working with drawdown records.

Drawdown records capture information on drawdowns. Since drawdowns are ranges, they subclass Ranges.

Warning

Drawdowns return both recovered AND active drawdowns, which may skew your performance results. To only consider recovered drawdowns, you should explicitly query `status_recovered` attribute.

Using Drawdowns.from_price(), you can generate drawdown records for any time series and analyze them right away.

    >>> from vectorbtpro import *

    >>> price = vbt.YFData.pull(
    ...     "BTC-USD",
    ...     start="2019-10 UTC",
    ...     end="2020-01 UTC"
    ... ).get('Close')

100%

    >>> price = price.rename(None)

    >>> drawdowns = vbt.Drawdowns.from_price(price, wrapper_kwargs=dict(freq='d'))

    >>> drawdowns.records_readable
       Drawdown Id  Column               Start Index              Valley Index  \
    0            0       0 2019-10-02 00:00:00+00:00 2019-10-06 00:00:00+00:00
    1            1       0 2019-10-09 00:00:00+00:00 2019-10-24 00:00:00+00:00
    2            2       0 2019-10-27 00:00:00+00:00 2019-12-17 00:00:00+00:00

                      End Index   Peak Value  Valley Value    End Value     Status
    0 2019-10-09 00:00:00+00:00  8393.041992   7988.155762  8595.740234  Recovered
    1 2019-10-25 00:00:00+00:00  8595.740234   7493.488770  8660.700195  Recovered
    2 2019-12-31 00:00:00+00:00  9551.714844   6640.515137  7193.599121     Active

    >>> drawdowns.duration.max(wrap_kwargs=dict(to_timedelta=True))
    Timedelta('66 days 00:00:00')

## From accessors

Moreover, all generic accessors have a property `drawdowns` and a method `get_drawdowns`:

    >>> # vectorbtpro.generic.accessors.GenericAccessor.drawdowns.coverage
    >>> price.vbt.drawdowns.coverage
    0.967391304347826

## Stats

Hint

See StatsBuilderMixin.stats() and Drawdowns.metrics.

    >>> df = pd.DataFrame({
    ...     'a': [1, 2, 1, 3, 2],
    ...     'b': [2, 3, 1, 2, 1]
    ... })

    >>> drawdowns = df.vbt(freq='d').drawdowns

    >>> drawdowns['a'].stats()
    Start                                        0
    End                                          4
    Period                         5 days 00:00:00
    Coverage [%]                              80.0
    Total Records                                2
    Total Recovered Drawdowns                    1
    Total Active Drawdowns                       1
    Active Drawdown [%]                  33.333333
    Active Duration                2 days 00:00:00
    Active Recovery [%]                        0.0
    Active Recovery Return [%]                 0.0
    Active Recovery Duration       0 days 00:00:00
    Max Drawdown [%]                          50.0
    Avg Drawdown [%]                          50.0
    Max Drawdown Duration          2 days 00:00:00
    Avg Drawdown Duration          2 days 00:00:00
    Max Recovery Return [%]                  200.0
    Avg Recovery Return [%]                  200.0
    Max Recovery Duration          1 days 00:00:00
    Avg Recovery Duration          1 days 00:00:00
    Avg Recovery Duration Ratio                1.0
    Name: a, dtype: object

By default, the metrics `max_dd`, `avg_dd`, `max_dd_duration`, and `avg_dd_duration` do not include active drawdowns. To change that, pass `incl_active=True`:

    >>> drawdowns['a'].stats(settings=dict(incl_active=True))
    Start                                        0
    End                                          4
    Period                         5 days 00:00:00
    Coverage [%]                              80.0
    Total Records                                2
    Total Recovered Drawdowns                    1
    Total Active Drawdowns                       1
    Active Drawdown [%]                  33.333333
    Active Duration                2 days 00:00:00
    Active Recovery [%]                        0.0
    Active Recovery Return [%]                 0.0
    Active Recovery Duration       0 days 00:00:00
    Max Drawdown [%]                          50.0
    Avg Drawdown [%]                     41.666667
    Max Drawdown Duration          2 days 00:00:00
    Avg Drawdown Duration          2 days 00:00:00
    Max Recovery Return [%]                  200.0
    Avg Recovery Return [%]                  200.0
    Max Recovery Duration          1 days 00:00:00
    Avg Recovery Duration          1 days 00:00:00
    Avg Recovery Duration Ratio                1.0
    Name: a, dtype: object

StatsBuilderMixin.stats() also supports (re-)grouping:

    >>> drawdowns['a'].stats(group_by=True)
    UserWarning: Metric 'active_dd' does not support grouped data
    UserWarning: Metric 'active_duration' does not support grouped data
    UserWarning: Metric 'active_recovery' does not support grouped data
    UserWarning: Metric 'active_recovery_return' does not support grouped data
    UserWarning: Metric 'active_recovery_duration' does not support grouped data

    Start                                        0
    End                                          4
    Period                         5 days 00:00:00
    Coverage [%]                              80.0
    Total Records                                2
    Total Recovered Drawdowns                    1
    Total Active Drawdowns                       1
    Max Drawdown [%]                          50.0
    Avg Drawdown [%]                          50.0
    Max Drawdown Duration          2 days 00:00:00
    Avg Drawdown Duration          2 days 00:00:00
    Max Recovery Return [%]                  200.0
    Avg Recovery Return [%]                  200.0
    Max Recovery Duration          1 days 00:00:00
    Avg Recovery Duration          1 days 00:00:00
    Avg Recovery Duration Ratio                1.0
    Name: group, dtype: object

## Plots

Hint

See PlotsBuilderMixin.plots() and Drawdowns.subplots.

Drawdowns class has a single subplot based on Drawdowns.plot():

    >>> drawdowns['a'].plots().show()

## dd_attach_field_config ReadonlyConfig

Config of fields to be attached to Drawdowns.

    ReadonlyConfig(
        status=dict(
            attach_filters=True
        )
    )

## dd_field_config ReadonlyConfig

Field config for Drawdowns.

    ReadonlyConfig(
        dtype=np.dtype([
            ('id', 'int64'),
            ('col', 'int64'),
            ('start_idx', 'int64'),
            ('valley_idx', 'int64'),
            ('end_idx', 'int64'),
            ('start_val', 'float64'),
            ('valley_val', 'float64'),
            ('end_val', 'float64'),
            ('status', 'int64')
        ]),
        settings=dict(
            id=dict(
                title='Drawdown Id'
            ),
            valley_idx=dict(
                title='Valley Index',
                mapping='index'
            ),
            start_val=dict(
                title='Start Value'
            ),
            valley_val=dict(
                title='Valley Value'
            ),
            end_val=dict(
                title='End Value'
            ),
            status=dict(
                mapping=DrawdownStatusT(
                    Active=0,
                    Recovered=1
                )
            )
        )
    )

## dd_shortcut_config ReadonlyConfig

Config of shortcut properties to be attached to Drawdowns.

    ReadonlyConfig(
        ranges=dict(),
        decline_ranges=dict(),
        recovery_ranges=dict(),
        drawdown=dict(
            obj_type='mapped_array'
        ),
        avg_drawdown=dict(
            obj_type='red_array'
        ),
        max_drawdown=dict(
            obj_type='red_array'
        ),
        recovery_return=dict(
            obj_type='mapped_array'
        ),
        avg_recovery_return=dict(
            obj_type='red_array'
        ),
        max_recovery_return=dict(
            obj_type='red_array'
        ),
        decline_duration=dict(
            obj_type='mapped_array'
        ),
        recovery_duration=dict(
            obj_type='mapped_array'
        ),
        recovery_duration_ratio=dict(
            obj_type='mapped_array'
        ),
        active_drawdown=dict(
            obj_type='red_array'
        ),
        active_duration=dict(
            obj_type='red_array'
        ),
        active_recovery=dict(
            obj_type='red_array'
        ),
        active_recovery_return=dict(
            obj_type='red_array'
        ),
        active_recovery_duration=dict(
            obj_type='red_array'
        )
    )

## Drawdowns class

    Drawdowns(
        wrapper,
        records_arr,
        open=None,
        high=None,
        low=None,
        close=None,
        **kwargs
    )

Extends Ranges for working with drawdown records.

Requires `records_arr` to have all fields defined in drawdown_dt.

Superclasses

- Analyzable
- AttrResolverMixin
- Cacheable
- Chainable
- Comparable
- Configured
- ExtPandasIndexer
- HasSettings
- IndexingBase
- PandasIndexer
- Pickleable
- PlotsBuilderMixin
- Prettified
- PriceRecords
- Ranges
- Records
- RecordsWithFields
- StatsBuilderMixin
- Wrapping

Inherited members

- AttrResolverMixin.deep_getattr()
- AttrResolverMixin.post_resolve_attr()
- AttrResolverMixin.pre_resolve_attr()
- AttrResolverMixin.resolve_attr()
- AttrResolverMixin.resolve_shortcut_attr()
- Cacheable.get_ca_setup()
- Chainable.pipe()
- Configured.copy()
- Configured.equals()
- Configured.get_writeable_attrs()
- Configured.prettify()
- Configured.resolve_merge_kwargs()
- Configured.update_config()
- HasSettings.get_path_setting()
- HasSettings.get_path_settings()
- HasSettings.get_setting()
- HasSettings.get_settings()
- HasSettings.has_path_setting()
- HasSettings.has_path_settings()
- HasSettings.has_setting()
- HasSettings.has_settings()
- HasSettings.reset_settings()
- HasSettings.resolve_setting()
- HasSettings.resolve_settings_paths()
- HasSettings.set_settings()
- IndexingBase.indexing_setter_func()
- PandasIndexer.xs()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()
- PlotsBuilderMixin.build_subplots_doc()
- PlotsBuilderMixin.override_subplots_doc()
- PlotsBuilderMixin.plots()
- PriceRecords.from_records()
- PriceRecords.get_bar_close()
- PriceRecords.get_bar_close_time()
- PriceRecords.get_bar_high()
- PriceRecords.get_bar_low()
- PriceRecords.get_bar_open()
- PriceRecords.get_bar_open_time()
- PriceRecords.indexing_func()
- PriceRecords.indexing_func_meta()
- PriceRecords.resample()
- PriceRecords.resolve_column_stack_kwargs()
- PriceRecords.resolve_row_stack_kwargs()
- Ranges.avg_duration
- Ranges.bar_close
- Ranges.bar_close_time
- Ranges.bar_high
- Ranges.bar_low
- Ranges.bar_open
- Ranges.bar_open_time
- Ranges.close
- Ranges.cls_dir
- Ranges.col
- Ranges.col_arr
- Ranges.col_mapper
- Ranges.column_only_select
- Ranges.config
- Ranges.coverage
- Ranges.crop()
- Ranges.duration
- Ranges.end_idx
- Ranges.field_names
- Ranges.filter_max_duration()
- Ranges.filter_min_duration()
- Ranges.first_idx
- Ranges.first_pd_mask
- Ranges.from_array()
- Ranges.from_delta()
- Ranges.get_avg_duration()
- Ranges.get_coverage()
- Ranges.get_duration()
- Ranges.get_first_idx()
- Ranges.get_first_pd_mask()
- Ranges.get_invalid()
- Ranges.get_last_idx()
- Ranges.get_last_pd_mask()
- Ranges.get_max_duration()
- Ranges.get_projections()
- Ranges.get_ranges_pd_mask()
- Ranges.get_real_duration()
- Ranges.get_valid()
- Ranges.group_select
- Ranges.high
- Ranges.id
- Ranges.id_arr
- Ranges.idx_arr
- Ranges.iloc
- Ranges.indexing_kwargs
- Ranges.invalid
- Ranges.last_idx
- Ranges.last_pd_mask
- Ranges.loc
- Ranges.low
- Ranges.max_duration
- Ranges.open
- Ranges.overlap_coverage
- Ranges.pd_mask
- Ranges.plot_projections()
- Ranges.plot_shapes()
- Ranges.projections
- Ranges.range_only_select
- Ranges.ranges_pd_mask
- Ranges.real_duration
- Ranges.rec_state
- Ranges.records
- Ranges.records_arr
- Ranges.records_readable
- Ranges.self_aliases
- Ranges.start_idx
- Ranges.status
- Ranges.status_closed
- Ranges.status_open
- Ranges.valid
- Ranges.values
- Ranges.with_delta()
- Ranges.wrapper
- Ranges.xloc
- Records.apply()
- Records.apply_mask()
- Records.build_field_config_doc()
- Records.column_stack()
- Records.column_stack_records_arrs()
- Records.count()
- Records.coverage_map()
- Records.first_n()
- Records.get_apply_mapping_arr()
- Records.get_apply_mapping_str_arr()
- Records.get_column_stack_record_indices()
- Records.get_field_arr()
- Records.get_field_mapping()
- Records.get_field_name()
- Records.get_field_setting()
- Records.get_field_title()
- Records.get_map_field()
- Records.get_map_field_to_columns()
- Records.get_map_field_to_index()
- Records.get_pd_mask()
- Records.get_row_stack_record_indices()
- Records.has_conflicts()
- Records.is_sorted()
- Records.last_n()
- Records.map()
- Records.map_array()
- Records.map_field()
- Records.override_field_config_doc()
- Records.prepare_customdata()
- Records.random_n()
- Records.replace()
- Records.resample_meta()
- Records.resample_records_arr()
- Records.row_stack()
- Records.row_stack_records_arrs()
- Records.select_cols()
- Records.sort()
- Records.to_readable()
- StatsBuilderMixin.build_metrics_doc()
- StatsBuilderMixin.override_metrics_doc()
- StatsBuilderMixin.stats()
- Wrapping.regroup()
- Wrapping.resolve_self()
- Wrapping.resolve_stack_kwargs()
- Wrapping.select_col()
- Wrapping.select_col_from_obj()
- Wrapping.split()

### active_drawdown property

Drawdowns.get_active_drawdown() with default arguments.

### active_duration property

Drawdowns.get_active_duration() with default arguments.

### active_recovery property

Drawdowns.get_active_recovery() with default arguments.

### active_recovery_duration property

Drawdowns.get_active_recovery_duration() with default arguments.

### active_recovery_return property

Drawdowns.get_active_recovery_return() with default arguments.

### avg_drawdown property

Drawdowns.get_avg_drawdown() with default arguments.

### avg_recovery_return property

Drawdowns.get_avg_recovery_return() with default arguments.

### decline_duration property

Drawdowns.get_decline_duration() with default arguments.

### decline_ranges property

Drawdowns.get_decline_ranges() with default arguments.

### drawdown property

Drawdowns.get_drawdown() with default arguments.

### end_val property

Mapped array of the field `end_val`.

### field_config class variable

Field config of Drawdowns.

    HybridConfig(
        dtype=np.dtype([
            ('id', 'int64'),
            ('col', 'int64'),
            ('start_idx', 'int64'),
            ('valley_idx', 'int64'),
            ('end_idx', 'int64'),
            ('start_val', 'float64'),
            ('valley_val', 'float64'),
            ('end_val', 'float64'),
            ('status', 'int64')
        ]),
        settings=dict(
            id=dict(
                name='id',
                title='Drawdown Id',
                mapping='ids'
            ),
            col=dict(
                name='col',
                title='Column',
                mapping='columns',
                as_customdata=False
            ),
            idx=dict(
                name='end_idx',
                title='Index',
                mapping='index'
            ),
            start_idx=dict(
                title='Start Index',
                mapping='index'
            ),
            end_idx=dict(
                title='End Index',
                mapping='index'
            ),
            status=dict(
                title='Status',
                mapping=DrawdownStatusT(
                    Active=0,
                    Recovered=1
                )
            ),
            valley_idx=dict(
                title='Valley Index',
                mapping='index'
            ),
            start_val=dict(
                title='Start Value'
            ),
            valley_val=dict(
                title='Valley Value'
            ),
            end_val=dict(
                title='End Value'
            )
        )
    )

Returns `Drawdowns._field_config`, which gets (hybrid-) copied upon creation of each instance. Thus, changing this config won't affect the class.

To change fields, you can either change the config in-place, override this property, or overwrite the instance variable `Drawdowns._field_config`.

### from_price class method

    Drawdowns.from_price(
        close,
        *,
        open=None,
        high=None,
        low=None,
        attach_data=True,
        jitted=None,
        chunked=None,
        wrapper_kwargs=None,
        **kwargs
    )

Build Drawdowns from price.

`**kwargs` will be passed to Drawdowns.

### get_active_drawdown method

    Drawdowns.get_active_drawdown(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None
    )

Get drawdown of the last active drawdown only.

Does not support grouping.

### get_active_duration method

    Drawdowns.get_active_duration(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get duration of the last active drawdown only.

Does not support grouping.

### get_active_recovery method

    Drawdowns.get_active_recovery(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None
    )

Get recovery of the last active drawdown only.

Does not support grouping.

### get_active_recovery_duration method

    Drawdowns.get_active_recovery_duration(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get recovery duration of the last active drawdown only.

Does not support grouping.

### get_active_recovery_return method

    Drawdowns.get_active_recovery_return(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get recovery return of the last active drawdown only.

Does not support grouping.

### get_avg_drawdown method

    Drawdowns.get_avg_drawdown(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get average drawdown (ADD).

Based on Drawdowns.drawdown.

### get_avg_recovery_return method

    Drawdowns.get_avg_recovery_return(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get average recovery return.

Based on Drawdowns.recovery_return.

### get_decline_duration method

    Drawdowns.get_decline_duration(
        jitted=None,
        chunked=None,
        **kwargs
    )

See dd_decline_duration_nb().

Takes into account both recovered and active drawdowns.

### get_decline_ranges method

    Drawdowns.get_decline_ranges(
        **kwargs
    )

Get records of type Ranges for peak-to-valley ranges.

### get_drawdown method

    Drawdowns.get_drawdown(
        jitted=None,
        chunked=None,
        **kwargs
    )

See dd_drawdown_nb().

Takes into account both recovered and active drawdowns.

### get_max_drawdown method

    Drawdowns.get_max_drawdown(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get maximum drawdown (MDD).

Based on Drawdowns.drawdown.

### get_max_recovery_return method

    Drawdowns.get_max_recovery_return(
        group_by=None,
        jitted=None,
        chunked=None,
        wrap_kwargs=None,
        **kwargs
    )

Get maximum recovery return.

Based on Drawdowns.recovery_return.

### get_ranges method

    Drawdowns.get_ranges(
        **kwargs
    )

Get records of type Ranges for peak-to-end ranges.

### get_recovery_duration method

    Drawdowns.get_recovery_duration(
        jitted=None,
        chunked=None,
        **kwargs
    )

See dd_recovery_duration_nb().

A value higher than 1 means the recovery was slower than the decline.

Takes into account both recovered and active drawdowns.

### get_recovery_duration_ratio method

    Drawdowns.get_recovery_duration_ratio(
        jitted=None,
        chunked=None,
        **kwargs
    )

See dd_recovery_duration_ratio_nb().

Takes into account both recovered and active drawdowns.

### get_recovery_ranges method

    Drawdowns.get_recovery_ranges(
        **kwargs
    )

Get records of type Ranges for valley-to-end ranges.

### get_recovery_return method

    Drawdowns.get_recovery_return(
        jitted=None,
        chunked=None,
        **kwargs
    )

See dd_recovery_return_nb().

Takes into account both recovered and active drawdowns.

### max_drawdown property

Drawdowns.get_max_drawdown() with default arguments.

### max_recovery_return property

Drawdowns.get_max_recovery_return() with default arguments.

### metrics class variable

Metrics supported by Drawdowns.

    HybridConfig(
        start=dict(
            title='Start',
            calc_func=<function Drawdowns.<lambda> at 0x7ff34a345d80>,
            agg_func=None,
            tags='wrapper'
        ),
        end=dict(
            title='End',
            calc_func=<function Drawdowns.<lambda> at 0x7ff34a345e10>,
            agg_func=None,
            tags='wrapper'
        ),
        period=dict(
            title='Period',
            calc_func=<function Drawdowns.<lambda> at 0x7ff34a345ea0>,
            apply_to_timedelta=True,
            agg_func=None,
            tags='wrapper'
        ),
        coverage=dict(
            title='Coverage [%]',
            calc_func='coverage',
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a345f30>,
            tags=[
                'ranges',
                'duration'
            ]
        ),
        total_records=dict(
            title='Total Records',
            calc_func='count',
            tags='records'
        ),
        total_recovered=dict(
            title='Total Recovered Drawdowns',
            calc_func='status_recovered.count',
            tags='drawdowns'
        ),
        total_active=dict(
            title='Total Active Drawdowns',
            calc_func='status_active.count',
            tags='drawdowns'
        ),
        active_dd=dict(
            title='Active Drawdown [%]',
            calc_func='active_drawdown',
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a345fc0>,
            check_is_not_grouped=True,
            tags=[
                'drawdowns',
                'active'
            ]
        ),
        active_duration=dict(
            title='Active Duration',
            calc_func='active_duration',
            fill_wrap_kwargs=True,
            check_is_not_grouped=True,
            tags=[
                'drawdowns',
                'active',
                'duration'
            ]
        ),
        active_recovery=dict(
            title='Active Recovery [%]',
            calc_func='active_recovery',
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a346050>,
            check_is_not_grouped=True,
            tags=[
                'drawdowns',
                'active'
            ]
        ),
        active_recovery_return=dict(
            title='Active Recovery Return [%]',
            calc_func='active_recovery_return',
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a3460e0>,
            check_is_not_grouped=True,
            tags=[
                'drawdowns',
                'active'
            ]
        ),
        active_recovery_duration=dict(
            title='Active Recovery Duration',
            calc_func='active_recovery_duration',
            fill_wrap_kwargs=True,
            check_is_not_grouped=True,
            tags=[
                'drawdowns',
                'active',
                'duration'
            ]
        ),
        max_dd=dict(
            title='Max Drawdown [%]',
            calc_func=RepEval(
                template="'max_drawdown' if incl_active else 'status_recovered.get_max_drawdown'",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            ),
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a346170>,
            tags=RepEval(
                template="['drawdowns'] if incl_active else ['drawdowns', 'recovered']",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            )
        ),
        avg_dd=dict(
            title='Avg Drawdown [%]',
            calc_func=RepEval(
                template="'avg_drawdown' if incl_active else 'status_recovered.get_avg_drawdown'",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            ),
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a346200>,
            tags=RepEval(
                template="['drawdowns'] if incl_active else ['drawdowns', 'recovered']",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            )
        ),
        max_dd_duration=dict(
            title='Max Drawdown Duration',
            calc_func=RepEval(
                template="'max_duration' if incl_active else 'status_recovered.get_max_duration'",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            ),
            fill_wrap_kwargs=True,
            tags=RepEval(
                template="['drawdowns', 'duration'] if incl_active else ['drawdowns', 'recovered', 'duration']",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            )
        ),
        avg_dd_duration=dict(
            title='Avg Drawdown Duration',
            calc_func=RepEval(
                template="'avg_duration' if incl_active else 'status_recovered.get_avg_duration'",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            ),
            fill_wrap_kwargs=True,
            tags=RepEval(
                template="['drawdowns', 'duration'] if incl_active else ['drawdowns', 'recovered', 'duration']",
                context=None,
                strict=None,
                sub_id=None,
                context_merge_kwargs=None
            )
        ),
        max_return=dict(
            title='Max Recovery Return [%]',
            calc_func='status_recovered.recovery_return.max',
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a346290>,
            tags=[
                'drawdowns',
                'recovered'
            ]
        ),
        avg_return=dict(
            title='Avg Recovery Return [%]',
            calc_func='status_recovered.recovery_return.mean',
            post_calc_func=<function Drawdowns.<lambda> at 0x7ff34a346320>,
            tags=[
                'drawdowns',
                'recovered'
            ]
        ),
        max_recovery_duration=dict(
            title='Max Recovery Duration',
            calc_func='status_recovered.recovery_duration.max',
            apply_to_timedelta=True,
            tags=[
                'drawdowns',
                'recovered',
                'duration'
            ]
        ),
        avg_recovery_duration=dict(
            title='Avg Recovery Duration',
            calc_func='status_recovered.recovery_duration.mean',
            apply_to_timedelta=True,
            tags=[
                'drawdowns',
                'recovered',
                'duration'
            ]
        ),
        recovery_duration_ratio=dict(
            title='Avg Recovery Duration Ratio',
            calc_func='status_recovered.recovery_duration_ratio.mean',
            tags=[
                'drawdowns',
                'recovered'
            ]
        )
    )

Returns `Drawdowns._metrics`, which gets (hybrid-) 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 `Drawdowns._metrics`.

### plot method

    Drawdowns.plot(
        column=None,
        top_n=5,
        plot_ohlc=True,
        plot_close=True,
        plot_markers=True,
        plot_zones=True,
        ohlc_type=None,
        ohlc_trace_kwargs=None,
        close_trace_kwargs=None,
        peak_trace_kwargs=None,
        valley_trace_kwargs=None,
        recovery_trace_kwargs=None,
        active_trace_kwargs=None,
        decline_shape_kwargs=None,
        recovery_shape_kwargs=None,
        active_shape_kwargs=None,
        add_trace_kwargs=None,
        xref='x',
        yref='y',
        fig=None,
        **layout_kwargs
    )

Plot drawdowns.

Args

`column` :`str`
  Name of the column to plot.
`top_n` :`int`
  Filter top N drawdown records by maximum drawdown.
`plot_ohlc` :`bool`
  Whether to plot OHLC.
`plot_close` :`bool`
  Whether to plot close.
`plot_markers` :`bool`
  Whether to plot markers.
`plot_zones` :`bool`
  Whether to plot zones.
`ohlc_type`

  Either 'OHLC', 'Candlestick' or Plotly trace.

  Pass None to use the default.

`ohlc_trace_kwargs` :`dict`
  Keyword arguments passed to `ohlc_type`.
`close_trace_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Scatter` for Drawdowns.close.
`peak_trace_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Scatter` for peak values.
`valley_trace_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Scatter` for valley values.
`recovery_trace_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Scatter` for recovery values.
`active_trace_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Scatter` for active recovery values.
`decline_shape_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Figure.add_shape` for decline zones.
`recovery_shape_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Figure.add_shape` for recovery zones.
`active_shape_kwargs` :`dict`
  Keyword arguments passed to `plotly.graph_objects.Figure.add_shape` for active recovery zones.
`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

    >>> index = pd.date_range("2020", periods=8)
    >>> price = pd.Series([1, 2, 1, 2, 3, 2, 1, 2], index=index)
    >>> vbt.Drawdowns.from_price(price, wrapper_kwargs=dict(freq='1 day')).plot().show()

### plots_defaults property

Defaults for PlotsBuilderMixin.plots().

Merges Ranges.plots_defaults and `plots` from drawdowns.

### ranges property

Drawdowns.get_ranges() with default arguments.

### recovery_duration property

Drawdowns.get_recovery_duration() with default arguments.

### recovery_duration_ratio property

Drawdowns.get_recovery_duration_ratio() with default arguments.

### recovery_ranges property

Drawdowns.get_recovery_ranges() with default arguments.

### recovery_return property

Drawdowns.get_recovery_return() with default arguments.

### start_val property

Mapped array of the field `start_val`.

### stats_defaults property

Defaults for StatsBuilderMixin.stats().

Merges Ranges.stats_defaults and `stats` from drawdowns.

### status_active property

Records filtered by `status == 0`.

### status_recovered property

Records filtered by `status == 1`.

### subplots class variable

Subplots supported by Drawdowns.

    HybridConfig(
        plot=dict(
            title='Drawdowns',
            check_is_not_grouped=True,
            plot_func='plot',
            tags='drawdowns'
        )
    )

Returns `Drawdowns._subplots`, which gets (hybrid-) 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 `Drawdowns._subplots`.

### valley_idx property

Mapped array of the field `valley_idx`.

### valley_val property

Mapped array of the field `valley_val`.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings