quantstats_lumi.reports

   1#!/usr/bin/env python
   2# -*- coding: UTF-8 -*-
   3#
   4# QuantStats: Portfolio analytics for quants
   5# https://github.com/ranaroussi/quantstats
   6#
   7# Copyright 2019-2023 Ran Aroussi
   8#
   9# Licensed under the Apache License, Version 2.0 (the "License");
  10# you may not use this file except in compliance with the License.
  11# You may obtain a copy of the License at
  12#
  13#     http://www.apache.org/licenses/LICENSE-2.0
  14#
  15# Unless required by applicable law or agreed to in writing, software
  16# distributed under the License is distributed on an "AS IS" BASIS,
  17# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18# See the License for the specific language governing permissions and
  19# limitations under the License.
  20
  21import re as _regex
  22from base64 import b64encode as _b64encode
  23from datetime import datetime as _dt
  24from io import StringIO
  25from math import ceil as _ceil
  26from math import sqrt as _sqrt
  27
  28import numpy as _np
  29import pandas as _pd
  30from dateutil.relativedelta import relativedelta
  31from tabulate import tabulate as _tabulate
  32
  33from . import __version__
  34from . import plots as _plots
  35from . import stats as _stats
  36from . import utils as _utils
  37
  38try:
  39    from IPython.display import HTML as iHTML
  40    from IPython.display import display as iDisplay
  41except ImportError:
  42    from IPython.core.display import HTML as iHTML
  43    from IPython.core.display import display as iDisplay
  44
  45
  46def _get_trading_periods(periods_per_year=365):
  47    """returns trading periods per year and half year"""
  48    half_year = _ceil(periods_per_year / 2)
  49    return periods_per_year, half_year
  50
  51
  52def _match_dates(returns, benchmark):
  53    """match dates of returns and benchmark"""
  54    fix_instance = lambda x: x[x.columns[0]] if isinstance(x, _pd.DataFrame) else x
  55    loc = max(fix_instance(returns).ne(0).idxmax(), fix_instance(benchmark).ne(0).idxmax())
  56    returns = returns.loc[loc:]
  57    benchmark = benchmark.loc[loc:]
  58
  59    return returns, benchmark
  60
  61
  62def html(
  63    returns,
  64    benchmark: _pd.Series = None,
  65    rf: float = 0.0,
  66    grayscale: bool = False,
  67    title: str = "Strategy Tearsheet",
  68    output: str = None,
  69    compounded: bool = True,
  70    periods_per_year: int = 365,
  71    download_filename: str = "tearsheet.html",
  72    figfmt: str = "svg",
  73    template_path: str = None,
  74    match_dates: bool = True,
  75    parameters: dict = None,
  76    log_scale: bool = False,
  77    show_match_volatility: bool = True,
  78    **kwargs,
  79):
  80    """
  81    Generates a full HTML tearsheet with performance metrics and plots
  82
  83    Parameters
  84    ----------
  85    returns : pd.Series, pd.DataFrame
  86        Strategy returns
  87    benchmark : pd.Series, optional
  88        Benchmark returns
  89    rf : float, optional
  90        Risk-free rate, default is 0
  91    grayscale : bool, optional
  92        Plot in grayscale, default is False
  93    title : str, optional
  94        Title of the HTML report, default is "Strategy Tearsheet"
  95    output : str, optional
  96        Output file path
  97    compounded : bool, optional
  98        Whether to use compounded returns, default is True
  99    periods_per_year : int, optional
 100        Trading periods per year, default is 365
 101    download_filename : str, optional
 102        Download filename, default is "tearsheet.html"
 103    figfmt : str, optional
 104        Figure format, default is "svg"
 105    template_path : str, optional
 106        Custom template path
 107    match_dates : bool, optional
 108        Match dates of returns and benchmark, default is True
 109    parameters : dict, optional
 110        Strategy parameters
 111
 112    Returns
 113    -------
 114    None
 115    """
 116
 117    if output is None and not _utils._in_notebook():
 118        raise ValueError("`output` must be specified")
 119
 120    if match_dates:
 121        returns = returns.dropna()
 122
 123    win_year, win_half_year = _get_trading_periods(periods_per_year)
 124
 125    tpl = ""
 126    with open(template_path or __file__[:-4] + ".html", encoding='utf-8') as f:
 127        tpl = f.read()
 128        f.close()
 129
 130    # prepare timeseries
 131    if match_dates:
 132        returns = returns.dropna()
 133    returns = _utils._prepare_returns(returns)
 134
 135    strategy_title = kwargs.get("strategy_title", "Strategy")
 136    if (
 137        isinstance(returns, _pd.DataFrame)
 138        and len(returns.columns) > 1
 139        and isinstance(strategy_title, str)
 140    ):
 141        strategy_title = list(returns.columns)
 142
 143    if benchmark is not None:
 144        benchmark_title = kwargs.get("benchmark_title", "Benchmark")
 145        if kwargs.get("benchmark_title") is None:
 146            if isinstance(benchmark, str):
 147                benchmark_title = benchmark
 148            elif isinstance(benchmark, _pd.Series):
 149                benchmark_title = benchmark.name
 150            elif isinstance(benchmark, _pd.DataFrame):
 151                benchmark_title = benchmark[benchmark.columns[0]].name
 152
 153        tpl = tpl.replace(
 154            "{{benchmark_title}}", f"Benchmark is {benchmark_title.upper()} | "
 155        )
 156        benchmark = _utils._prepare_benchmark(benchmark, returns.index, rf)
 157        if match_dates is True:
 158            returns, benchmark = _match_dates(returns, benchmark)
 159    else:
 160        benchmark_title = None
 161
 162    # Assign names/columns after all preparations and matching
 163    if benchmark is not None:
 164        benchmark.name = benchmark_title
 165    if isinstance(returns, _pd.Series):
 166        returns.name = strategy_title
 167    elif isinstance(returns, _pd.DataFrame):
 168        returns.columns = strategy_title
 169
 170    # Check for no trades condition
 171    no_trades_occurred = False
 172    if returns.empty:
 173        no_trades_occurred = True
 174    else:
 175        sum_abs_returns = 0.0
 176        if isinstance(returns, _pd.Series):
 177            # Assuming returns is numeric after _prepare_returns
 178            sum_abs_returns = returns.abs().sum()
 179        elif isinstance(returns, _pd.DataFrame):
 180            # Assuming returns DataFrame columns are numeric after _prepare_returns
 181            sum_abs_returns = returns.select_dtypes(include=[_np.number]).abs().sum().sum()
 182        
 183        if abs(sum_abs_returns) < 1e-9: # Using a small epsilon for float comparison
 184            no_trades_occurred = True
 185
 186    no_trades_html_message = ""
 187    if no_trades_occurred:
 188        no_trades_html_message = "<div style='text-align: center; padding: 10px; background-color: #fff3cd; color: #856404; border: 1px solid #ffeeba; border-radius: .25rem; margin-bottom: 1rem;'><strong>Note:</strong> No trades or significant activity occurred during this period. Metrics shown below may reflect this.</div>"
 189
 190    date_range = returns.index.strftime("%e %b, %Y")
 191    tpl = tpl.replace("{{date_range}}", date_range[0] + " - " + date_range[-1])
 192    tpl = tpl.replace("{{title}}", title)
 193    tpl = tpl.replace("{{v}}", __version__)
 194
 195    if benchmark is not None:
 196        benchmark.name = benchmark_title
 197    if isinstance(returns, _pd.Series):
 198        returns.name = strategy_title
 199    elif isinstance(returns, _pd.DataFrame):
 200        returns.columns = strategy_title
 201
 202    mtrx = metrics(
 203        returns=returns,
 204        benchmark=benchmark,
 205        rf=rf,
 206        display=False,
 207        mode="full",
 208        sep=True,
 209        internal="True",
 210        compounded=compounded,
 211        periods_per_year=periods_per_year,
 212        prepare_returns=False,
 213        benchmark_title=benchmark_title,
 214        strategy_title=strategy_title,
 215    )[2:]
 216
 217    mtrx.index.name = "Metric"
 218    # tpl = tpl.replace("{{metrics}}", _html_table(mtrx)) # Original line
 219    
 220    # Modified replacement for metrics table
 221    metrics_table_html = _html_table(mtrx)
 222    # The "no trades" message is no longer prepended here.
 223    tpl = tpl.replace("{{metrics}}", metrics_table_html, 1)
 224
 225    # Add all of the summary metrics
 226    # Ensure these are cast to str and the no_trades_html_message is NOT with CAGR here.
 227
 228    # CAGR #
 229    cagr_value = mtrx.loc["CAGR% (Annual Return)", strategy_title]
 230    # Ensure CAGR is formatted as a percentage string with 2 decimals
 231    if isinstance(cagr_value, float):
 232        cagr_str = f"{cagr_value:.2f}%"
 233    else:
 234        cagr_str = str(cagr_value)
 235    tpl = tpl.replace("{{cagr}}", cagr_str)
 236
 237    # Total Return #
 238    total_return_value = mtrx.loc["Total Return", strategy_title]
 239    # Ensure Total Return is formatted as a percentage string with 2 decimals
 240    if isinstance(total_return_value, float):
 241        total_return_str = f"{total_return_value:.2f}%"
 242    else:
 243        total_return_str = str(total_return_value)
 244    tpl = tpl.replace("{{total_return}}", total_return_str)
 245
 246    # Max Drawdown #
 247    max_drawdown_value = mtrx.loc["Max Drawdown", strategy_title]
 248    if isinstance(max_drawdown_value, float):
 249        max_drawdown_str = f"{max_drawdown_value:.2f}%"
 250    else:
 251        max_drawdown_str = str(max_drawdown_value)
 252    tpl = tpl.replace("{{max_drawdown}}", max_drawdown_str)
 253
 254    # RoMaD #
 255    romad_value = mtrx.loc["RoMaD", strategy_title]
 256    if isinstance(romad_value, float):
 257        romad_str = f"{romad_value:.2f}"
 258    else:
 259        romad_str = str(romad_value)
 260    tpl = tpl.replace("{{romad}}", romad_str)
 261
 262    # Longest Drawdown Duration #
 263    longest_dd_days_value = mtrx.loc["Longest DD Days", strategy_title]
 264    tpl = tpl.replace("{{longest_dd_days}}", str(longest_dd_days_value))
 265
 266    # Sharpe #
 267    sharpe_value = mtrx.loc["Sharpe", strategy_title]
 268    if isinstance(sharpe_value, float):
 269        sharpe_str = f"{sharpe_value:.2f}"
 270    else:
 271        sharpe_str = str(sharpe_value)
 272    tpl = tpl.replace("{{sharpe}}", sharpe_str)
 273
 274    # Sortino #
 275    sortino_value = mtrx.loc["Sortino", strategy_title]
 276    if isinstance(sortino_value, float):
 277        sortino_str = f"{sortino_value:.2f}"
 278    else:
 279        sortino_str = str(sortino_value)
 280    tpl = tpl.replace("{{sortino}}", sortino_str)
 281
 282
 283    if isinstance(returns, _pd.DataFrame):
 284        num_cols = len(returns.columns)
 285        for i in reversed(range(num_cols + 1, num_cols + 3)):
 286            str_td = "<td></td>" * i
 287            tpl = tpl.replace(
 288                f"<tr>{str_td}</tr>", '<tr><td colspan="{}"><hr></td></tr>'.format(i)
 289            )
 290
 291    tpl = tpl.replace(
 292        "<tr><td></td><td></td><td></td></tr>", '<tr><td colspan="3"><hr></td></tr>'
 293    )
 294    tpl = tpl.replace(
 295        "<tr><td></td><td></td></tr>", '<tr><td colspan="2"><hr></td></tr>'
 296    )
 297
 298    if parameters is not None:
 299        tpl = tpl.replace("{{parameters_section}}", parameters_section(parameters))
 300
 301    if benchmark is not None:
 302        yoy = _stats.compare(
 303            returns, benchmark, "YE", compounded=compounded, prepare_returns=False
 304        )
 305        if isinstance(returns, _pd.Series):
 306            yoy.columns = [benchmark_title, strategy_title, "Multiplier", "Won"]
 307        elif isinstance(returns, _pd.DataFrame):
 308            yoy.columns = list(
 309                _pd.core.common.flatten([benchmark_title, strategy_title])
 310            )
 311        yoy.index.name = "Year"
 312        tpl = tpl.replace("{{eoy_title}}", "<h3>EOY Returns vs Benchmark</h3>")
 313        tpl = tpl.replace("{{eoy_table}}", _html_table(yoy))
 314    else:
 315        # pct multiplier
 316        yoy = _pd.DataFrame(_utils.group_returns(returns, returns.index.year) * 100)
 317        if isinstance(returns, _pd.Series):
 318            yoy.columns = ["Return"]
 319            yoy["Cumulative"] = _utils.group_returns(returns, returns.index.year, True)
 320            yoy["Return"] = yoy["Return"].round(2).astype(str) + "%"
 321            yoy["Cumulative"] = (yoy["Cumulative"] * 100).round(2).astype(str) + "%"
 322        elif isinstance(returns, _pd.DataFrame):
 323            # Don't show cumulative for multiple strategy portfolios
 324            # just show compounded like when we have a benchmark
 325            yoy.columns = list(_pd.core.common.flatten(strategy_title))
 326
 327        yoy.index.name = "Year"
 328        tpl = tpl.replace("{{eoy_title}}", "<h3>EOY Returns</h3>")
 329        tpl = tpl.replace("{{eoy_table}}", _html_table(yoy))
 330
 331    if isinstance(returns, _pd.Series):
 332        dd = _stats.to_drawdown_series(returns)
 333        dd_info = _stats.drawdown_details(dd).sort_values(
 334            by="max drawdown", ascending=True
 335        )[:10]
 336        dd_info = dd_info[["start", "end", "max drawdown", "days"]]
 337        dd_info.columns = ["Started", "Recovered", "Drawdown", "Days"]
 338        tpl = tpl.replace("{{dd_info}}", _html_table(dd_info, False))
 339    elif isinstance(returns, _pd.DataFrame):
 340        dd_info_list = []
 341        for col in returns.columns:
 342            dd = _stats.to_drawdown_series(returns[col])
 343            dd_info = _stats.drawdown_details(dd).sort_values(
 344                by="max drawdown", ascending=True
 345            )[:10]
 346            dd_info = dd_info[["start", "end", "max drawdown", "days"]]
 347            dd_info.columns = ["Started", "Recovered", "Drawdown", "Days"]
 348            dd_info_list.append(_html_table(dd_info, False))
 349
 350        dd_html_table = ""
 351        for html_str, col in zip(dd_info_list, returns.columns):
 352            dd_html_table = (
 353                dd_html_table + f"<h3>{col}</h3><br>" + StringIO(html_str).read()
 354            )
 355        tpl = tpl.replace("{{dd_info}}", dd_html_table)
 356
 357    active = kwargs.get("active_returns", False)
 358    # plots
 359    plot_returns = _plots.log_returns if log_scale else _plots.returns
 360    placeholder_returns = "{{log_returns}}" if log_scale else "{{returns}}"
 361
 362    figfile = _utils._file_stream()
 363    plot_returns(
 364        returns,
 365        benchmark,
 366        grayscale=grayscale,
 367        figsize=(8, 5),
 368        subtitle=False,
 369        savefig={"fname": figfile, "format": figfmt},
 370        show=False,
 371        ylabel=False,
 372        cumulative=compounded,
 373        prepare_returns=False,
 374    )
 375    first_plot_html = _embed_figure(figfile, figfmt) # Get the HTML for the first plot
 376
 377    # Prepend the no_trades_html_message if no trades occurred, then add the plot
 378    if no_trades_occurred:
 379        tpl = tpl.replace(placeholder_returns, no_trades_html_message + first_plot_html, 1)
 380    else:
 381        tpl = tpl.replace(placeholder_returns, first_plot_html, 1)
 382
 383    if benchmark is not None and show_match_volatility:
 384        figfile = _utils._file_stream()
 385        plot_returns(
 386            returns,
 387            benchmark,
 388            match_volatility=True,
 389            grayscale=grayscale,
 390            figsize=(8, 5),
 391            subtitle=False,
 392            savefig={"fname": figfile, "format": figfmt},
 393            show=False,
 394            ylabel=False,
 395            cumulative=compounded,
 396            prepare_returns=False,
 397        )
 398        tpl = tpl.replace("{{vol_returns}}", _embed_figure(figfile, figfmt))
 399
 400    figfile = _utils._file_stream()
 401    _plots.yearly_returns(
 402        returns,
 403        benchmark,
 404        grayscale=grayscale,
 405        figsize=(8, 4),
 406        subtitle=False,
 407        savefig={"fname": figfile, "format": figfmt},
 408        show=False,
 409        ylabel=False,
 410        compounded=compounded,
 411        prepare_returns=False,
 412    )
 413    tpl = tpl.replace("{{eoy_returns}}", _embed_figure(figfile, figfmt))
 414
 415    figfile = _utils._file_stream()
 416    _plots.histogram(
 417        returns,
 418        benchmark,
 419        grayscale=grayscale,
 420        figsize=(7, 4),
 421        subtitle=False,
 422        savefig={"fname": figfile, "format": figfmt},
 423        show=False,
 424        ylabel=False,
 425        compounded=compounded,
 426        prepare_returns=False,
 427    )
 428    tpl = tpl.replace("{{monthly_dist}}", _embed_figure(figfile, figfmt))
 429
 430    figfile = _utils._file_stream()
 431    _plots.daily_returns(
 432        returns,
 433        benchmark,
 434        grayscale=grayscale,
 435        figsize=(8, 3),
 436        subtitle=False,
 437        savefig={"fname": figfile, "format": figfmt},
 438        show=False,
 439        ylabel=False,
 440        prepare_returns=False,
 441        active=active,
 442    )
 443    tpl = tpl.replace("{{daily_returns}}", _embed_figure(figfile, figfmt))
 444
 445    if benchmark is not None:
 446        figfile = _utils._file_stream()
 447        _plots.rolling_beta(
 448            returns,
 449            benchmark,
 450            grayscale=grayscale,
 451            figsize=(8, 3),
 452            subtitle=False,
 453            window1=win_half_year,
 454            window2=win_year,
 455            savefig={"fname": figfile, "format": figfmt},
 456            show=False,
 457            ylabel=False,
 458            prepare_returns=False,
 459        )
 460        tpl = tpl.replace("{{rolling_beta}}", _embed_figure(figfile, figfmt))
 461
 462    figfile = _utils._file_stream()
 463    _plots.rolling_volatility(
 464        returns,
 465        benchmark,
 466        grayscale=grayscale,
 467        figsize=(8, 3),
 468        subtitle=False,
 469        savefig={"fname": figfile, "format": figfmt},
 470        show=False,
 471        ylabel=False,
 472        period=win_half_year,
 473        periods_per_year=win_year,
 474    )
 475    tpl = tpl.replace("{{rolling_vol}}", _embed_figure(figfile, figfmt))
 476
 477    figfile = _utils._file_stream()
 478    _plots.rolling_sharpe(
 479        returns,
 480        grayscale=grayscale,
 481        figsize=(8, 3),
 482        subtitle=False,
 483        savefig={"fname": figfile, "format": figfmt},
 484        show=False,
 485        ylabel=False,
 486        period=win_half_year,
 487        periods_per_year=win_year,
 488    )
 489    tpl = tpl.replace("{{rolling_sharpe}}", _embed_figure(figfile, figfmt))
 490
 491    figfile = _utils._file_stream()
 492    _plots.rolling_sortino(
 493        returns,
 494        grayscale=grayscale,
 495        figsize=(8, 3),
 496        subtitle=False,
 497        savefig={"fname": figfile, "format": figfmt},
 498        show=False,
 499        ylabel=False,
 500        period=win_half_year,
 501        periods_per_year=win_year,
 502    )
 503    tpl = tpl.replace("{{rolling_sortino}}", _embed_figure(figfile, figfmt))
 504
 505    figfile = _utils._file_stream()
 506    if isinstance(returns, _pd.Series):
 507        _plots.drawdowns_periods(
 508            returns,
 509            grayscale=grayscale,
 510            figsize=(8, 4),
 511            subtitle=False,
 512            title=returns.name,
 513            savefig={"fname": figfile, "format": figfmt},
 514            show=False,
 515            ylabel=False,
 516            compounded=compounded,
 517            prepare_returns=False,
 518            log_scale=log_scale,
 519        )
 520        tpl = tpl.replace("{{dd_periods}}", _embed_figure(figfile, figfmt))
 521    elif isinstance(returns, _pd.DataFrame):
 522        embed = []
 523        for col in returns.columns:
 524            _plots.drawdowns_periods(
 525                returns[col],
 526                grayscale=grayscale,
 527                figsize=(8, 4),
 528                subtitle=False,
 529                title=col,
 530                savefig={"fname": figfile, "format": figfmt},
 531                show=False,
 532                ylabel=False,
 533                compounded=compounded,
 534                prepare_returns=False,
 535            )
 536            embed.append(figfile)
 537        tpl = tpl.replace("{{dd_periods}}", _embed_figure(embed, figfmt))
 538
 539    figfile = _utils._file_stream()
 540    _plots.drawdown(
 541        returns,
 542        grayscale=grayscale,
 543        figsize=(8, 3),
 544        subtitle=False,
 545        savefig={"fname": figfile, "format": figfmt},
 546        show=False,
 547        ylabel=False,
 548    )
 549    tpl = tpl.replace("{{dd_plot}}", _embed_figure(figfile, figfmt))
 550
 551    figfile = _utils._file_stream()
 552    if isinstance(returns, _pd.Series):
 553        _plots.monthly_heatmap(
 554            returns,
 555            benchmark,
 556            grayscale=grayscale,
 557            figsize=(8, 4),
 558            cbar=False,
 559            returns_label=returns.name,
 560            savefig={"fname": figfile, "format": figfmt},
 561            show=False,
 562            ylabel=False,
 563            compounded=compounded,
 564            active=active,
 565        )
 566        tpl = tpl.replace("{{monthly_heatmap}}", _embed_figure(figfile, figfmt))
 567    elif isinstance(returns, _pd.DataFrame):
 568        embed = []
 569        for col in returns.columns:
 570            _plots.monthly_heatmap(
 571                returns[col],
 572                benchmark,
 573                grayscale=grayscale,
 574                figsize=(8, 4),
 575                cbar=False,
 576                returns_label=col,
 577                savefig={"fname": figfile, "format": figfmt},
 578                show=False,
 579                ylabel=False,
 580                compounded=compounded,
 581                active=active,
 582            )
 583            embed.append(figfile)
 584        tpl = tpl.replace("{{monthly_heatmap}}", _embed_figure(embed, figfmt))
 585
 586    figfile = _utils._file_stream()
 587
 588    if isinstance(returns, _pd.Series):
 589        _plots.distribution(
 590            returns,
 591            grayscale=grayscale,
 592            figsize=(8, 4),
 593            subtitle=False,
 594            title=returns.name,
 595            savefig={"fname": figfile, "format": figfmt},
 596            show=False,
 597            ylabel=False,
 598            compounded=compounded,
 599            prepare_returns=False,
 600        )
 601        tpl = tpl.replace("{{returns_dist}}", _embed_figure(figfile, figfmt))
 602    elif isinstance(returns, _pd.DataFrame):
 603        embed = []
 604        for col in returns.columns:
 605            _plots.distribution(
 606                returns[col],
 607                grayscale=grayscale,
 608                figsize=(8, 4),
 609                subtitle=False,
 610                title=col,
 611                savefig={"fname": figfile, "format": figfmt},
 612                show=False,
 613                ylabel=False,
 614                compounded=compounded,
 615                prepare_returns=False,
 616            )
 617            embed.append(figfile)
 618        tpl = tpl.replace("{{returns_dist}}", _embed_figure(embed, figfmt))
 619
 620    tpl = _regex.sub(r"\{\{(.*?)\}\}", "", tpl)
 621    tpl = tpl.replace("white-space:pre;", "")
 622
 623    if output is None:
 624        # _open_html(tpl)
 625        _download_html(tpl, download_filename)
 626        return
 627
 628    with open(output, "w", encoding="utf-8") as f:
 629        f.write(tpl)
 630
 631    print(f"HTML report saved to: {output}")
 632
 633    # Return the metrics
 634    return mtrx
 635
 636
 637def full(
 638    returns,
 639    benchmark=None,
 640    rf=0.0,
 641    grayscale=False,
 642    figsize=(8, 5),
 643    display=True,
 644    compounded=True,
 645    periods_per_year=365,
 646    match_dates=True,
 647    **kwargs,
 648):
 649    """calculates and plots full performance metrics"""
 650
 651    # prepare timeseries
 652    if match_dates:
 653        returns = returns.dropna()
 654    returns = _utils._prepare_returns(returns)
 655    if benchmark is not None:
 656        benchmark = _utils._prepare_benchmark(benchmark, returns.index, rf)
 657        if match_dates is True:
 658            returns, benchmark = _match_dates(returns, benchmark)
 659
 660    benchmark_title = None
 661    if benchmark is not None:
 662        benchmark_title = kwargs.get("benchmark_title", "Benchmark")
 663    strategy_title = kwargs.get("strategy_title", "Strategy")
 664    active = kwargs.get("active_returns", False)
 665
 666    if (
 667        isinstance(returns, _pd.DataFrame)
 668        and len(returns.columns) > 1
 669        and isinstance(strategy_title, str)
 670    ):
 671        strategy_title = list(returns.columns)
 672
 673    if benchmark is not None:
 674        benchmark.name = benchmark_title
 675    if isinstance(returns, _pd.Series):
 676        returns.name = strategy_title
 677    elif isinstance(returns, _pd.DataFrame):
 678        returns.columns = strategy_title
 679
 680    dd = _stats.to_drawdown_series(returns)
 681
 682    if isinstance(dd, _pd.Series):
 683        col = _stats.drawdown_details(dd).columns[4]
 684        dd_info = _stats.drawdown_details(dd).sort_values(by=col, ascending=True)[:5]
 685        if not dd_info.empty:
 686            dd_info.index = range(1, min(6, len(dd_info) + 1))
 687            dd_info.columns = map(lambda x: str(x).title(), dd_info.columns)
 688    elif isinstance(dd, _pd.DataFrame):
 689        col = _stats.drawdown_details(dd).columns.get_level_values(1)[4]
 690        dd_info_dict = {}
 691        for ptf in dd.columns:
 692            dd_info = _stats.drawdown_details(dd[ptf]).sort_values(
 693                by=col, ascending=True
 694            )[:5]
 695            if not dd_info.empty:
 696                dd_info.index = range(1, min(6, len(dd_info) + 1))
 697                dd_info.columns = map(lambda x: str(x).title(), dd_info.columns)
 698            dd_info_dict[ptf] = dd_info
 699
 700    if _utils._in_notebook():
 701        iDisplay(iHTML("<h4>Performance Metrics</h4>"))
 702        iDisplay(
 703            metrics(
 704                returns=returns,
 705                benchmark=benchmark,
 706                rf=rf,
 707                display=display,
 708                mode="full",
 709                compounded=compounded,
 710                periods_per_year=periods_per_year,
 711                prepare_returns=False,
 712                benchmark_title=benchmark_title,
 713                strategy_title=strategy_title,
 714            )
 715        )
 716
 717        if isinstance(dd, _pd.Series):
 718            iDisplay(iHTML('<h4 style="margin-bottom:20px">Worst 5 Drawdowns</h4>'))
 719            if dd_info.empty:
 720                iDisplay(iHTML("<p>(no drawdowns)</p>"))
 721            else:
 722                iDisplay(dd_info)
 723        elif isinstance(dd, _pd.DataFrame):
 724            for ptf, dd_info in dd_info_dict.items():
 725                iDisplay(
 726                    iHTML(
 727                        '<h4 style="margin-bottom:20px">%s - Worst 5 Drawdowns</h4>'
 728                        % ptf
 729                    )
 730                )
 731                if dd_info.empty:
 732                    iDisplay(iHTML("<p>(no drawdowns)</p>"))
 733                else:
 734                    iDisplay(dd_info)
 735
 736        iDisplay(iHTML("<h4>Strategy Visualization</h4>"))
 737    else:
 738        print("[Performance Metrics]\n")
 739        metrics(
 740            returns=returns,
 741            benchmark=benchmark,
 742            rf=rf,
 743            display=display,
 744            mode="full",
 745            compounded=compounded,
 746            periods_per_year=periods_per_year,
 747            prepare_returns=False,
 748            benchmark_title=benchmark_title,
 749            strategy_title=strategy_title,
 750        )
 751        print("\n\n")
 752        print("[Worst 5 Drawdowns]\n")
 753        if isinstance(dd, _pd.Series):
 754            if dd_info.empty:
 755                print("(no drawdowns)")
 756            else:
 757                print(
 758                    _tabulate(
 759                        dd_info, headers="keys", tablefmt="simple", floatfmt=".2f"
 760                    )
 761                )
 762        elif isinstance(dd, _pd.DataFrame):
 763            for ptf, dd_info in dd_info_dict.items():
 764                if dd_info.empty:
 765                    print("(no drawdowns)")
 766                else:
 767                    print(f"{ptf}\n")
 768                    print(
 769                        _tabulate(
 770                            dd_info, headers="keys", tablefmt="simple", floatfmt=".2f"
 771                        )
 772                    )
 773
 774        print("\n\n")
 775        print("[Strategy Visualization]\nvia Matplotlib")
 776
 777    plots(
 778        returns=returns,
 779        benchmark=benchmark,
 780        grayscale=grayscale,
 781        figsize=figsize,
 782        mode="full",
 783        periods_per_year=periods_per_year,
 784        prepare_returns=False,
 785        benchmark_title=benchmark_title,
 786        strategy_title=strategy_title,
 787        active=active,
 788    )
 789
 790def basic(
 791    returns,
 792    benchmark=None,
 793    rf=0.0,
 794    grayscale=False,
 795    figsize=(8, 5),
 796    display=True,
 797    compounded=True,
 798    periods_per_year=365,
 799    match_dates=True,
 800    **kwargs,
 801):
 802    """calculates and plots basic performance metrics"""
 803
 804    # prepare timeseries
 805    if match_dates:
 806        returns = returns.dropna()
 807    returns = _utils._prepare_returns(returns)
 808    if benchmark is not None:
 809        benchmark = _utils._prepare_benchmark(benchmark, returns.index, rf)
 810        if match_dates is True:
 811            returns, benchmark = _match_dates(returns, benchmark)
 812
 813    benchmark_title = None
 814    if benchmark is not None:
 815        benchmark_title = kwargs.get("benchmark_title", "Benchmark")
 816    strategy_title = kwargs.get("strategy_title", "Strategy")
 817    active = kwargs.get("active_returns", False)
 818
 819    if (
 820        isinstance(returns, _pd.DataFrame)
 821        and len(returns.columns) > 1
 822        and isinstance(strategy_title, str)
 823    ):
 824        strategy_title = list(returns.columns)
 825
 826    if _utils._in_notebook():
 827        iDisplay(iHTML("<h4>Performance Metrics</h4>"))
 828        metrics(
 829            returns=returns,
 830            benchmark=benchmark,
 831            rf=rf,
 832            display=display,
 833            mode="basic",
 834            compounded=compounded,
 835            periods_per_year=periods_per_year,
 836            prepare_returns=False,
 837            benchmark_title=benchmark_title,
 838            strategy_title=strategy_title,
 839        )
 840        iDisplay(iHTML("<h4>Strategy Visualization</h4>"))
 841    else:
 842        print("[Performance Metrics]\n")
 843        metrics(
 844            returns=returns,
 845            benchmark=benchmark,
 846            rf=rf,
 847            display=display,
 848            mode="basic",
 849            compounded=compounded,
 850            periods_per_year=periods_per_year,
 851            prepare_returns=False,
 852            benchmark_title=benchmark_title,
 853            strategy_title=strategy_title,
 854        )
 855
 856        print("\n\n")
 857        print("[Strategy Visualization]\nvia Matplotlib")
 858
 859    plots(
 860        returns=returns,
 861        benchmark=benchmark,
 862        grayscale=grayscale,
 863        figsize=figsize,
 864        mode="basic",
 865        periods_per_year=periods_per_year,
 866        prepare_returns=False,
 867        benchmark_title=benchmark_title,
 868        strategy_title=strategy_title,
 869        active=active,
 870    )
 871
 872def parameters_section(parameters):
 873    """returns a formatted section for strategy parameters"""
 874    if parameters is None:
 875        return ""
 876
 877    tpl = """
 878    <div id="params">
 879        <h3>Parameters Used</h3>
 880        <table style="width:100%; font-size: 12px">
 881    """
 882
 883    # Add titles to the table
 884    tpl += "<thead><tr><th>Parameter</th><th>Value</th></tr></thead>"
 885
 886    for key, value in parameters.items():
 887        # Make sure that the value is something that can be displayed
 888        if not isinstance(value, (int, float, str)):
 889            value = str(value)
 890
 891        tpl += f"<tr><td>{key}</td><td>{value}</td></tr>"
 892    tpl += """
 893        </table>
 894    </div>
 895    """
 896
 897    return tpl
 898
 899def metrics(
 900    returns,
 901    benchmark=None,
 902    rf=0.0,
 903    display=True,
 904    mode="basic",
 905    sep=False,
 906    compounded=True,
 907    periods_per_year=365,
 908    prepare_returns=True,
 909    match_dates=True,
 910    **kwargs,
 911):
 912    """calculates and displays various performance metrics"""
 913
 914    if match_dates:
 915        returns = returns.dropna()
 916    returns.index = returns.index.tz_localize(None)
 917    win_year, _ = _get_trading_periods(periods_per_year)
 918
 919    benchmark_colname = kwargs.get("benchmark_title", "Benchmark")
 920    strategy_colname = kwargs.get("strategy_title", "Strategy")
 921
 922    if benchmark is not None:
 923        if isinstance(benchmark, str):
 924            benchmark_colname = f"Benchmark ({benchmark.upper()})"
 925        elif isinstance(benchmark, _pd.DataFrame) and len(benchmark.columns) > 1:
 926            raise ValueError(
 927                "`benchmark` must be a pandas Series, "
 928                "but a multi-column DataFrame was passed"
 929            )
 930
 931    if isinstance(returns, _pd.DataFrame):
 932        if len(returns.columns) > 1:
 933            blank = [""] * len(returns.columns)
 934            if isinstance(strategy_colname, str):
 935                strategy_colname = list(returns.columns)
 936    else:
 937        blank = [""]
 938
 939    if prepare_returns:
 940        df = _utils._prepare_returns(returns)
 941
 942    if isinstance(returns, _pd.Series):
 943        df = _pd.DataFrame({"returns": returns})
 944    elif isinstance(returns, _pd.DataFrame):
 945        df = _pd.DataFrame(
 946            {
 947                "returns_" + str(i + 1): returns[strategy_col]
 948                for i, strategy_col in enumerate(returns.columns)
 949            }
 950        )
 951
 952    if benchmark is not None:
 953        benchmark = _utils._prepare_benchmark(benchmark, returns.index, rf)
 954        if match_dates is True:
 955            returns, benchmark = _match_dates(returns, benchmark)
 956        df["benchmark"] = benchmark
 957        if isinstance(returns, _pd.Series):
 958            blank = ["", ""]
 959            df["returns"] = returns
 960        elif isinstance(returns, _pd.DataFrame):
 961            blank = [""] * len(returns.columns) + [""]
 962            for i, strategy_col in enumerate(returns.columns):
 963                df["returns_" + str(i + 1)] = returns[strategy_col]
 964
 965    if isinstance(returns, _pd.Series):
 966        s_start = {"returns": df["returns"].index.strftime("%Y-%m-%d")[0]}
 967        s_end = {"returns": df["returns"].index.strftime("%Y-%m-%d")[-1]}
 968        s_rf = {"returns": rf}
 969    elif isinstance(returns, _pd.DataFrame):
 970        df_strategy_columns = [col for col in df.columns if col != "benchmark"]
 971        s_start = {
 972            strategy_col: df[strategy_col].dropna().index.strftime("%Y-%m-%d")[0]
 973            for strategy_col in df_strategy_columns
 974        }
 975        s_end = {
 976            strategy_col: df[strategy_col].dropna().index.strftime("%Y-%m-%d")[-1]
 977            for strategy_col in df_strategy_columns
 978        }
 979        s_rf = {strategy_col: rf for strategy_col in df_strategy_columns}
 980
 981    if "benchmark" in df:
 982        s_start["benchmark"] = df["benchmark"].index.strftime("%Y-%m-%d")[0]
 983        s_end["benchmark"] = df["benchmark"].index.strftime("%Y-%m-%d")[-1]
 984        s_rf["benchmark"] = rf
 985
 986    df = df.fillna(0)
 987
 988    # pct multiplier
 989    pct = 100 if display or "internal" in kwargs else 1
 990    if kwargs.get("as_pct", False):
 991        pct = 100
 992
 993    # return df
 994    dd = _calc_dd(
 995        df,
 996        display=(display or "internal" in kwargs),
 997        as_pct=kwargs.get("as_pct", False),
 998    )
 999
1000    metrics = _pd.DataFrame()
1001    metrics["Start Period"] = _pd.Series(s_start)
1002    metrics["End Period"] = _pd.Series(s_end)
1003    metrics["Risk-Free Rate % "] = _pd.Series(s_rf) * 100
1004    metrics["Time in Market % "] = _stats.exposure(df, prepare_returns=False) * pct
1005
1006    metrics["~"] = blank
1007
1008    if compounded:
1009        metrics["Total Return"] = (_stats.comp(df) * pct).map("{:,.0f}%".format)  # No decimals for readability as it is a large number
1010    else:
1011        metrics["Total Return"] = (df.sum() * pct).map("{:,.2f}%".format)
1012
1013    metrics["CAGR% (Annual Return) "] = _stats.cagr(df, rf, compounded, win_year) * pct
1014
1015    metrics["~~~~~~~~~~~~~~"] = blank
1016
1017    metrics["Sharpe"] = _stats.sharpe(df, rf, win_year, True)
1018    metrics["RoMaD"] = _stats.romad(df, win_year, True)
1019
1020    if benchmark is not None:
1021        metrics["Corr to Benchmark "] = _stats.benchmark_correlation(df, benchmark, True)
1022    metrics["Prob. Sharpe Ratio %"] = (
1023        _stats.probabilistic_sharpe_ratio(df, rf, win_year, False) * pct
1024    )
1025    if mode.lower() == "full":
1026        metrics["Smart Sharpe"] = _stats.smart_sharpe(df, rf, win_year, True)
1027
1028    metrics["Sortino"] = _stats.sortino(df, rf, win_year, True)
1029    if mode.lower() == "full":
1030        metrics["Smart Sortino"] = _stats.smart_sortino(df, rf, win_year, True)
1031
1032    metrics["Sortino/√2"] = metrics["Sortino"] / _sqrt(2)
1033    if mode.lower() == "full":
1034        metrics["Smart Sortino/√2"] = metrics["Smart Sortino"] / _sqrt(2)
1035    metrics["Omega"] = _stats.omega(df, rf, 0.0, win_year)
1036
1037    metrics["~~~~~~~~"] = blank
1038    metrics["Max Drawdown %"] = blank
1039    metrics["Longest DD Days"] = blank
1040
1041    if mode.lower() == "full":
1042        if isinstance(returns, _pd.Series):
1043            ret_vol = (
1044                _stats.volatility(df["returns"], win_year, True, prepare_returns=False)
1045                * pct
1046            )
1047        elif isinstance(returns, _pd.DataFrame):
1048            ret_vol = [
1049                _stats.volatility(
1050                    df[strategy_col], win_year, True, prepare_returns=False
1051                )
1052                * pct
1053                for strategy_col in df_strategy_columns
1054            ]
1055        if "benchmark" in df:
1056            bench_vol = (
1057                _stats.volatility(
1058                    df["benchmark"], win_year, True, prepare_returns=False
1059                )
1060                * pct
1061            )
1062
1063            vol_ = [ret_vol, bench_vol]
1064            if isinstance(ret_vol, list):
1065                metrics["Volatility (ann.) %"] = list(_pd.core.common.flatten(vol_))
1066            else:
1067                metrics["Volatility (ann.) %"] = vol_
1068
1069            if isinstance(returns, _pd.Series):
1070                metrics["R^2"] = _stats.r_squared(
1071                    df["returns"], df["benchmark"], prepare_returns=False
1072                )
1073                metrics["Information Ratio"] = _stats.information_ratio(
1074                    df["returns"], df["benchmark"], prepare_returns=False
1075                )
1076            elif isinstance(returns, _pd.DataFrame):
1077                metrics["R^2"] = (
1078                    [
1079                        _stats.r_squared(
1080                            df[strategy_col], df["benchmark"], prepare_returns=False
1081                        ).round(2)
1082                        for strategy_col in df_strategy_columns
1083                    ]
1084                ) + ["-"]
1085                metrics["Information Ratio"] = (
1086                    [
1087                        _stats.information_ratio(
1088                            df[strategy_col], df["benchmark"], prepare_returns=False
1089                        ).round(2)
1090                        for strategy_col in df_strategy_columns
1091                    ]
1092                ) + ["-"]
1093        else:
1094            if isinstance(returns, _pd.Series):
1095                metrics["Volatility (ann.) %"] = [ret_vol]
1096            elif isinstance(returns, _pd.DataFrame):
1097                metrics["Volatility (ann.) %"] = ret_vol
1098
1099        metrics["Calmar"] = _stats.calmar(df, prepare_returns=False, periods=win_year)
1100        metrics["Skew"] = _stats.skew(df, prepare_returns=False)
1101        metrics["Kurtosis"] = _stats.kurtosis(df, prepare_returns=False)
1102
1103        metrics["~~~~~~~~~~"] = blank
1104
1105        metrics["Expected Daily %%"] = (
1106            _stats.expected_return(df, compounded=compounded, prepare_returns=False)
1107            * pct
1108        )
1109        metrics["Expected Monthly %%"] = (
1110            _stats.expected_return(
1111                df, compounded=compounded, aggregate="ME", prepare_returns=False
1112            )
1113            * pct
1114        )
1115        metrics["Expected Yearly %%"] = (
1116            _stats.expected_return(
1117                df, compounded=compounded, aggregate="YE", prepare_returns=False
1118            )
1119            * pct
1120        )
1121
1122        metrics["Daily Value-at-Risk %"] = -abs(
1123            _stats.var(df, prepare_returns=False) * pct
1124        )
1125        metrics["Expected Shortfall (cVaR) %"] = -abs(
1126            _stats.cvar(df, prepare_returns=False) * pct
1127        )
1128
1129    # returns
1130    metrics["~~"] = blank
1131    comp_func = _stats.comp if compounded else lambda x: _np.sum(x, axis=0)
1132
1133    today = df.index[-1]  # _dt.today()
1134    metrics["MTD %"] = comp_func(df[df.index >= _dt(today.year, today.month, 1)]) * pct
1135
1136    d = today - relativedelta(months=3)
1137    metrics["3M %"] = comp_func(df[df.index >= d]) * pct
1138
1139    d = today - relativedelta(months=6)
1140    metrics["6M %"] = comp_func(df[df.index >= d]) * pct
1141
1142    metrics["YTD %"] = comp_func(df[df.index >= _dt(today.year, 1, 1)]) * pct
1143
1144    d = today - relativedelta(years=1)
1145    metrics["1Y %"] = comp_func(df[df.index >= d]) * pct
1146
1147    d = today - relativedelta(months=35)
1148    metrics["3Y (ann.) %"] = (
1149        _stats.cagr(df[df.index >= d], 0.0, compounded, win_year) * pct
1150    )
1151
1152    d = today - relativedelta(months=59)
1153    metrics["5Y (ann.) %"] = (
1154        _stats.cagr(df[df.index >= d], 0.0, compounded, win_year) * pct
1155    )
1156
1157    d = today - relativedelta(years=10)
1158    metrics["10Y (ann.) %"] = (
1159        _stats.cagr(df[df.index >= d], 0.0, compounded, win_year) * pct
1160    )
1161
1162    metrics["All-time (ann.) %"] = _stats.cagr(df, 0.0, compounded, win_year) * pct
1163
1164    # best/worst
1165    if mode.lower() == "full":
1166        metrics["~~~"] = blank
1167        metrics["Best Day %"] = (
1168            _stats.best(df, compounded=compounded, prepare_returns=False) * pct
1169        )
1170        metrics["Worst Day %"] = _stats.worst(df, prepare_returns=False) * pct
1171        metrics["Best Month %"] = (
1172            _stats.best(
1173                df, compounded=compounded, aggregate="ME", prepare_returns=False
1174            )
1175            * pct
1176        )
1177        metrics["Worst Month %"] = (
1178            _stats.worst(df, aggregate="ME", prepare_returns=False) * pct
1179        )
1180        metrics["Best Year %"] = (
1181            _stats.best(
1182                df, compounded=compounded, aggregate="YE", prepare_returns=False
1183            )
1184            * pct
1185        )
1186        metrics["Worst Year %"] = (
1187            _stats.worst(
1188                df, compounded=compounded, aggregate="YE", prepare_returns=False
1189            )
1190            * pct
1191        )
1192
1193    # dd
1194    metrics["~~~~"] = blank
1195    for ix, row in dd.iterrows():
1196        metrics[ix] = row
1197    metrics["Recovery Factor"] = _stats.recovery_factor(df)
1198    metrics["Ulcer Index"] = _stats.ulcer_index(df)
1199    metrics["Serenity Index"] = _stats.serenity_index(df, rf)
1200
1201    # win rate
1202    if mode.lower() == "full":
1203        metrics["~~~~~"] = blank
1204        metrics["Avg. Up Month %"] = (
1205            _stats.avg_win(
1206                df, compounded=compounded, aggregate="ME", prepare_returns=False
1207            )
1208            * pct
1209        )
1210        metrics["Avg. Down Month %"] = (
1211            _stats.avg_loss(
1212                df, compounded=compounded, aggregate="ME", prepare_returns=False
1213            )
1214            * pct
1215        )
1216
1217        # Get the win rate
1218        win_rate = _stats.win_rate(df, prepare_returns=False)
1219
1220        # Number of win days in total
1221        metrics["Win Days"] = win_rate * len(df)
1222
1223        # Number of loss days in total
1224        metrics["Loss Days"] = len(df) - metrics["Win Days"]
1225
1226        metrics["Win Days %%"] = win_rate * pct
1227        metrics["Win Month %%"] = (
1228            _stats.win_rate(
1229                df, compounded=compounded, aggregate="ME", prepare_returns=False
1230            )
1231            * pct
1232        )
1233        metrics["Win Quarter %%"] = (
1234            _stats.win_rate(
1235                df, compounded=compounded, aggregate="QE", prepare_returns=False
1236            )
1237            * pct
1238        )
1239        metrics["Win Year %%"] = (
1240            _stats.win_rate(
1241                df, compounded=compounded, aggregate="YE", prepare_returns=False
1242            )
1243            * pct
1244        )
1245
1246        if "benchmark" in df:
1247            metrics["~~~~~~~~~~~~"] = blank
1248            if isinstance(returns, _pd.Series):
1249                greeks = _stats.greeks(
1250                    df["returns"], df["benchmark"], win_year, prepare_returns=False
1251                )
1252                metrics["Beta"] = [str(round(greeks["beta"], 2)), "-"]
1253                metrics["Alpha"] = [str(round(greeks["alpha"], 2)), "-"]
1254                metrics["Correlation"] = [
1255                    str(round(df["benchmark"].corr(df["returns"]) * pct, 2)) + "%",
1256                    "-",
1257                ]
1258                metrics["Treynor Ratio"] = [
1259                    str(
1260                        round(
1261                            _stats.treynor_ratio(
1262                                df["returns"], df["benchmark"], win_year, rf
1263                            )
1264                            * pct,
1265                            2,
1266                        )
1267                    )
1268                    + "%",
1269                    "-",
1270                ]
1271            elif isinstance(returns, _pd.DataFrame):
1272                greeks = [
1273                    _stats.greeks(
1274                        df[strategy_col],
1275                        df["benchmark"],
1276                        win_year,
1277                        prepare_returns=False,
1278                    )
1279                    for strategy_col in df_strategy_columns
1280                ]
1281                metrics["Beta"] = [str(round(g["beta"], 2)) for g in greeks] + ["-"]
1282                metrics["Alpha"] = [str(round(g["alpha"], 2)) for g in greeks] + ["-"]
1283                metrics["Correlation"] = (
1284                    [
1285                        str(round(df["benchmark"].corr(df[strategy_col]) * pct, 2))
1286                        + "%"
1287                        for strategy_col in strategy_colname
1288                    ]
1289                ) + ["-"]
1290                metrics["Treynor Ratio"] = (
1291                    [
1292                        str(
1293                            round(
1294                                _stats.treynor_ratio(
1295                                    df[strategy_col], df["benchmark"], win_year, rf
1296                                )
1297                                * pct,
1298                                2,
1299                            )
1300                        )
1301                        + "%"
1302                        for strategy_col in strategy_colname
1303                    ]
1304                ) + ["-"]
1305
1306    # prepare for display
1307    for col in metrics.columns:
1308        try:
1309            metrics[col] = metrics[col].astype(float).round(2)
1310            if display or "internal" in kwargs:
1311                metrics[col] = metrics[col].astype(str)
1312        except Exception:
1313            pass
1314        if (display or "internal" in kwargs) and "*int" in col:
1315            metrics[col] = metrics[col].str.replace(".0", "", regex=False)
1316            metrics.rename({col: col.replace("*int", "")}, axis=1, inplace=True)
1317        if (display or "internal" in kwargs) and "%" in col:
1318            metrics[col] = metrics[col] + "%"
1319
1320    try:
1321        metrics["Longest DD Days"] = _pd.to_numeric(metrics["Longest DD Days"]).astype(
1322            "int"
1323        )
1324        metrics["Avg. Drawdown Days"] = _pd.to_numeric(
1325            metrics["Avg. Drawdown Days"]
1326        ).astype("int")
1327
1328        if display or "internal" in kwargs:
1329            metrics["Longest DD Days"] = metrics["Longest DD Days"].astype(str)
1330            metrics["Avg. Drawdown Days"] = metrics["Avg. Drawdown Days"].astype(str)
1331    except Exception:
1332        metrics["Longest DD Days"] = "-"
1333        metrics["Avg. Drawdown Days"] = "-"
1334        if display or "internal" in kwargs:
1335            metrics["Longest DD Days"] = "-"
1336            metrics["Avg. Drawdown Days"] = "-"
1337
1338    metrics.columns = [col if "~" not in col else "" for col in metrics.columns]
1339    metrics = metrics.T
1340
1341    if "benchmark" in df:
1342        column_names = [strategy_colname, benchmark_colname]
1343        if isinstance(strategy_colname, list):
1344            metrics.columns = list(_pd.core.common.flatten(column_names))
1345        else:
1346            metrics.columns = column_names
1347    else:
1348        if isinstance(strategy_colname, list):
1349            metrics.columns = strategy_colname
1350        else:
1351            metrics.columns = [strategy_colname]
1352
1353    # cleanups
1354    metrics.replace([-0, "-0"], 0, inplace=True)
1355    metrics.replace(
1356        [
1357            _np.nan,
1358            -_np.nan,
1359            _np.inf,
1360            -_np.inf,
1361            "-nan%",
1362            "nan%",
1363            "-nan",
1364            "nan",
1365            "-inf%",
1366            "inf%",
1367            "-inf",
1368            "inf",
1369        ],
1370        "-",
1371        inplace=True,
1372    )
1373
1374    # move benchmark to be the first column always if present
1375    if "benchmark" in df:
1376        metrics = metrics[
1377            [benchmark_colname]
1378            + [col for col in metrics.columns if col != benchmark_colname]
1379        ]
1380
1381    if display:
1382        print(_tabulate(metrics, headers="keys", tablefmt="simple"))
1383        return None
1384
1385    if not sep:
1386        metrics = metrics[metrics.index != ""]
1387
1388    # remove spaces from column names
1389    metrics = metrics.T
1390    metrics.columns = [
1391        c.replace(" %", "").replace(" *int", "").strip() for c in metrics.columns
1392    ]
1393    metrics = metrics.T
1394
1395    return metrics
1396
1397
1398def plots(
1399    returns,
1400    benchmark=None,
1401    grayscale=False,
1402    figsize=(8, 5),
1403    mode="basic",
1404    compounded=True,
1405    periods_per_year=365,
1406    prepare_returns=True,
1407    match_dates=True,
1408    **kwargs,
1409):
1410    """Plots for strategy performance"""
1411
1412    benchmark_colname = kwargs.get("benchmark_title", "Benchmark")
1413    strategy_colname = kwargs.get("strategy_title", "Strategy")
1414    active = kwargs.get("active", "False")
1415
1416    if (
1417        isinstance(returns, _pd.DataFrame)
1418        and len(returns.columns) > 1
1419        and isinstance(strategy_colname, str)
1420    ):
1421        strategy_colname = list(returns.columns)
1422
1423    win_year, win_half_year = _get_trading_periods(periods_per_year)
1424
1425    if match_dates is True:
1426        returns = returns.dropna()
1427
1428    if prepare_returns:
1429        returns = _utils._prepare_returns(returns)
1430
1431    if isinstance(returns, _pd.Series):
1432        returns.name = strategy_colname
1433    elif isinstance(returns, _pd.DataFrame):
1434        returns.columns = strategy_colname
1435
1436    if mode.lower() != "full":
1437        _plots.snapshot(
1438            returns,
1439            grayscale=grayscale,
1440            figsize=(figsize[0], figsize[0]),
1441            show=True,
1442            mode=("comp" if compounded else "sum"),
1443            benchmark_title=benchmark_colname,
1444            strategy_title=strategy_colname,
1445        )
1446
1447        if isinstance(returns, _pd.Series):
1448            _plots.monthly_heatmap(
1449                returns,
1450                benchmark,
1451                grayscale=grayscale,
1452                figsize=(figsize[0], figsize[0] * 0.5),
1453                show=True,
1454                ylabel=False,
1455                compounded=compounded,
1456                active=active,
1457            )
1458        elif isinstance(returns, _pd.DataFrame):
1459            for col in returns.columns:
1460                _plots.monthly_heatmap(
1461                    returns[col].dropna(),
1462                    benchmark,
1463                    grayscale=grayscale,
1464                    figsize=(figsize[0], figsize[0] * 0.5),
1465                    show=True,
1466                    ylabel=False,
1467                    returns_label=col,
1468                    compounded=compounded,
1469                    active=active,
1470                )
1471
1472        return
1473
1474    returns = _pd.DataFrame(returns)
1475
1476    # prepare timeseries
1477    if benchmark is not None:
1478        benchmark = _utils._prepare_benchmark(benchmark, returns.index)
1479        benchmark.name = benchmark_colname
1480        if match_dates is True:
1481            returns, benchmark = _match_dates(returns, benchmark)
1482
1483    _plots.returns(
1484        returns,
1485        benchmark,
1486        grayscale=grayscale,
1487        figsize=(figsize[0], figsize[0] * 0.6),
1488        show=True,
1489        ylabel=False,
1490        prepare_returns=False,
1491    )
1492
1493    _plots.log_returns(
1494        returns,
1495        benchmark,
1496        grayscale=grayscale,
1497        figsize=(figsize[0], figsize[0] * 0.5),
1498        show=True,
1499        ylabel=False,
1500        prepare_returns=False,
1501    )
1502
1503    if benchmark is not None:
1504        _plots.returns(
1505            returns,
1506            benchmark,
1507            match_volatility=True,
1508            grayscale=grayscale,
1509            figsize=(figsize[0], figsize[0] * 0.5),
1510            show=True,
1511            ylabel=False,
1512            prepare_returns=False,
1513        )
1514
1515    _plots.yearly_returns(
1516        returns,
1517        benchmark,
1518        grayscale=grayscale,
1519        figsize=(figsize[0], figsize[0] * 0.5),
1520        show=True,
1521        ylabel=False,
1522        prepare_returns=False,
1523    )
1524
1525    _plots.histogram(
1526        returns,
1527        benchmark,
1528        grayscale=grayscale,
1529        figsize=(figsize[0], figsize[0] * 0.5),
1530        show=True,
1531        ylabel=False,
1532        prepare_returns=False,
1533    )
1534
1535    small_fig_size = (figsize[0], figsize[0] * 0.35)
1536    if len(returns.columns) > 1:
1537        small_fig_size = (
1538            figsize[0],
1539            figsize[0] * (0.33 * (len(returns.columns) * 0.66)),
1540        )
1541
1542    _plots.daily_returns(
1543        returns,
1544        benchmark,
1545        grayscale=grayscale,
1546        figsize=small_fig_size,
1547        show=True,
1548        ylabel=False,
1549        prepare_returns=False,
1550        active=active,
1551    )
1552
1553    if benchmark is not None:
1554        _plots.rolling_beta(
1555            returns,
1556            benchmark,
1557            grayscale=grayscale,
1558            window1=win_half_year,
1559            window2=win_year,
1560            figsize=small_fig_size,
1561            show=True,
1562            ylabel=False,
1563            prepare_returns=False,
1564        )
1565
1566    _plots.rolling_volatility(
1567        returns,
1568        benchmark,
1569        grayscale=grayscale,
1570        figsize=small_fig_size,
1571        show=True,
1572        ylabel=False,
1573        period=win_half_year,
1574    )
1575
1576    _plots.rolling_sharpe(
1577        returns,
1578        grayscale=grayscale,
1579        figsize=small_fig_size,
1580        show=True,
1581        ylabel=False,
1582        period=win_half_year,
1583    )
1584
1585    _plots.rolling_sortino(
1586        returns,
1587        grayscale=grayscale,
1588        figsize=small_fig_size,
1589        show=True,
1590        ylabel=False,
1591        period=win_half_year,
1592    )
1593
1594    if isinstance(returns, _pd.Series):
1595        _plots.drawdowns_periods(
1596            returns,
1597            grayscale=grayscale,
1598            figsize=(figsize[0], figsize[0] * 0.5),
1599            show=True,
1600            ylabel=False,
1601            prepare_returns=False,
1602        )
1603    elif isinstance(returns, _pd.DataFrame):
1604        for col in returns.columns:
1605            _plots.drawdowns_periods(
1606                returns[col],
1607                grayscale=grayscale,
1608                figsize=(figsize[0], figsize[0] * 0.5),
1609                show=True,
1610                ylabel=False,
1611                title=col,
1612                prepare_returns=False,
1613            )
1614
1615    _plots.drawdown(
1616        returns,
1617        grayscale=grayscale,
1618        figsize=(figsize[0], figsize[0] * 0.4),
1619        show=True,
1620        ylabel=False,
1621    )
1622
1623    if isinstance(returns, _pd.Series):
1624        _plots.monthly_heatmap(
1625            returns,
1626            benchmark,
1627            grayscale=grayscale,
1628            figsize=(figsize[0], figsize[0] * 0.5),
1629            returns_label=returns.name,
1630            show=True,
1631            ylabel=False,
1632            active=active,
1633        )
1634    elif isinstance(returns, _pd.DataFrame):
1635        for col in returns.columns:
1636            _plots.monthly_heatmap(
1637                returns[col],
1638                benchmark,
1639                grayscale=grayscale,
1640                figsize=(figsize[0], figsize[0] * 0.5),
1641                show=True,
1642                ylabel=False,
1643                returns_label=col,
1644                compounded=compounded,
1645                active=active,
1646            )
1647
1648    if isinstance(returns, _pd.Series):
1649        _plots.distribution(
1650            returns,
1651            grayscale=grayscale,
1652            figsize=(figsize[0], figsize[0] * 0.5),
1653            show=True,
1654            title=returns.name,
1655            ylabel=False,
1656            prepare_returns=False,
1657        )
1658    elif isinstance(returns, _pd.DataFrame):
1659        for col in returns.columns:
1660            _plots.distribution(
1661                returns[col],
1662                grayscale=grayscale,
1663                figsize=(figsize[0], figsize[0] * 0.5),
1664                show=True,
1665                title=col,
1666                ylabel=False,
1667                prepare_returns=False,
1668            )
1669
1670
1671def _calc_dd(df, display=True, as_pct=False):
1672    """Returns drawdown stats"""
1673    dd = _stats.to_drawdown_series(df)
1674    dd_info = _stats.drawdown_details(dd)
1675
1676    if dd_info.empty:
1677        return _pd.DataFrame()
1678
1679    if "returns" in dd_info:
1680        ret_dd = dd_info["returns"]
1681    # to match multiple columns like returns_1, returns_2, ...
1682    elif (
1683        any(dd_info.columns.get_level_values(0).str.contains("returns"))
1684        and dd_info.columns.get_level_values(0).nunique() > 1
1685    ):
1686        ret_dd = dd_info.loc[
1687            :, dd_info.columns.get_level_values(0).str.contains("returns")
1688        ]
1689    else:
1690        ret_dd = dd_info
1691
1692    if (
1693        any(ret_dd.columns.get_level_values(0).str.contains("returns"))
1694        and ret_dd.columns.get_level_values(0).nunique() > 1
1695    ):
1696        dd_stats = {
1697            col: {
1698                "Max Drawdown %": ret_dd[col]
1699                .sort_values(by="max drawdown", ascending=True)["max drawdown"]
1700                .values[0]
1701                / 100,
1702                "Longest DD Days": str(
1703                    _np.round(
1704                        ret_dd[col]
1705                        .sort_values(by="days", ascending=False)["days"]
1706                        .values[0]
1707                    )
1708                ),
1709                "Avg. Drawdown %": ret_dd[col]["max drawdown"].mean() / 100,
1710                "Avg. Drawdown Days": str(_np.round(ret_dd[col]["days"].mean())),
1711            }
1712            for col in ret_dd.columns.get_level_values(0)
1713        }
1714    else:
1715        dd_stats = {
1716            "returns": {
1717                "Max Drawdown %": ret_dd.sort_values(by="max drawdown", ascending=True)[
1718                    "max drawdown"
1719                ].values[0]
1720                / 100,
1721                "Longest DD Days": str(
1722                    _np.round(
1723                        ret_dd.sort_values(by="days", ascending=False)["days"].values[0]
1724                    )
1725                ),
1726                "Avg. Drawdown %": ret_dd["max drawdown"].mean() / 100,
1727                "Avg. Drawdown Days": str(_np.round(ret_dd["days"].mean())),
1728            }
1729        }
1730    if "benchmark" in df and (dd_info.columns, _pd.MultiIndex):
1731        bench_dd = dd_info["benchmark"].sort_values(by="max drawdown")
1732        dd_stats["benchmark"] = {
1733            "Max Drawdown %": bench_dd.sort_values(by="max drawdown", ascending=True)[
1734                "max drawdown"
1735            ].values[0]
1736            / 100,
1737            "Longest DD Days": str(
1738                _np.round(
1739                    bench_dd.sort_values(by="days", ascending=False)["days"].values[0]
1740                )
1741            ),
1742            "Avg. Drawdown %": bench_dd["max drawdown"].mean() / 100,
1743            "Avg. Drawdown Days": str(_np.round(bench_dd["days"].mean())),
1744        }
1745
1746    # pct multiplier
1747    pct = 100 if display or as_pct else 1
1748
1749    dd_stats = _pd.DataFrame(dd_stats).T
1750    dd_stats["Max Drawdown %"] = dd_stats["Max Drawdown %"].astype(float) * pct
1751    dd_stats["Avg. Drawdown %"] = dd_stats["Avg. Drawdown %"].astype(float) * pct
1752
1753    return dd_stats.T
1754
1755
1756def _html_table(obj, showindex="default"):
1757    """Returns HTML table"""
1758    obj = _tabulate(
1759        obj, headers="keys", tablefmt="html", floatfmt=".2f", showindex=showindex
1760    )
1761    obj = obj.replace(' style="text-align: right;"', "")
1762    obj = obj.replace(' style="text-align: left;"', "")
1763    obj = obj.replace(' style="text-align: center;"', "")
1764    obj = _regex.sub("<td> +", "<td>", obj)
1765    obj = _regex.sub(" +</td>", "</td>", obj)
1766    obj = _regex.sub("<th> +", "<th>", obj)
1767    obj = _regex.sub(" +</th>", "</th>", obj)
1768    return obj
1769
1770
1771def _download_html(html, filename="quantstats-tearsheet.html"):
1772    """Downloads HTML report"""
1773    jscode = _regex.sub(
1774        " +",
1775        " ",
1776        """<script>
1777    var bl=new Blob(['{{html}}'],{type:"text/html"});
1778    var a=document.createElement("a");
1779    a.href=URL.createObjectURL(bl);
1780    a.download="{{filename}}";
1781    a.hidden=true;document.body.appendChild(a);
1782    a.innerHTML="download report";
1783    a.click();</script>""".replace("\n", ""),
1784    )
1785    jscode = jscode.replace("{{html}}", _regex.sub(" +", " ", html.replace("\n", "")))
1786    if _utils._in_notebook():
1787        iDisplay(iHTML(jscode.replace("{{filename}}", filename)))
1788
1789
1790def _open_html(html):
1791    """Opens HTML in a new tab"""
1792    jscode = _regex.sub(
1793        " +",
1794        " ",
1795        """<script>
1796    var win=window.open();win.document.body.innerHTML='{{html}}';
1797    </script>""".replace("\n", ""),
1798    )
1799    jscode = jscode.replace("{{html}}", _regex.sub(" +", " ", html.replace("\n", "")))
1800    if _utils._in_notebook():
1801        iDisplay(iHTML(jscode))
1802
1803
1804def _embed_figure(figfiles, figfmt):
1805    """Embeds the figure bytes in the html output"""
1806    if isinstance(figfiles, list):
1807        embed_string = "\n"
1808        for figfile in figfiles:
1809            figbytes = figfile.getvalue()
1810            if figfmt == "svg":
1811                return figbytes.decode()
1812            data_uri = _b64encode(figbytes).decode()
1813            embed_string.join(
1814                '<img src="data:image/{};base64,{}" />'.format(figfmt, data_uri)
1815            )
1816    else:
1817        figbytes = figfiles.getvalue()
1818        if figfmt == "svg":
1819            return figbytes.decode()
1820        data_uri = _b64encode(figbytes).decode()
1821        embed_string = '<img src="data:image/{};base64,{}" />'.format(figfmt, data_uri)
1822    return embed_string