jquantstats 0.0.2__py3-none-any.whl

jquantstats/_plots.py

@@ -0,0 +1,308 @@
+import calendar
+import dataclasses
+
+import numpy as np
+import plotly.graph_objects as go
+import polars as pl
+from plotly.subplots import make_subplots
+
+
+@dataclasses.dataclass(frozen=True)
+class Plots:
+    data: "_Data"  # type: ignore
+
+    _FLATUI_COLORS = [
+        "#FEDD78",  # Yellow
+        "#348DC1",  # Blue
+        "#BA516B",  # Rose
+        "#4FA487",  # Green
+        "#9B59B6",  # Purple
+        "#613F66",  # Dark Purple
+        "#84B082",  # Light Green
+        "#DC136C",  # Pink
+        "#559CAD",  # Light Blue
+        "#4A5899",  # Navy Blue
+    ]
+
+    @staticmethod
+    def _get_colors():
+        """
+        Returns the default color palette and styling parameters for plots.
+
+        Returns:
+            tuple: A tuple containing:
+                - colors (list): List of hex color codes
+                - ls (str): Line style ("-" for solid)
+                - alpha (float): Opacity value (0.8)
+        """
+        colors = Plots._FLATUI_COLORS
+        ls = "-"  # Line style
+        alpha = 0.8  # Opacity
+        return colors, ls, alpha
+
+    @staticmethod
+    def _compsum(returns):
+        """Calculates rolling compounded returns"""
+        return returns.add(1).cumprod(axis=0) - 1
+
+    def plot_returns_bars(self):
+        """
+        Creates a bar chart of returns for each asset in the data.
+
+        This function visualizes the returns of each asset as bars, making it easy
+        to compare performance across different time periods.
+
+        Args:
+            data (_Data): A Data object containing returns data to plot.
+
+        Returns:
+            plotly.graph_objects.Figure: A Plotly figure object containing the bar chart.
+                The figure shows returns for each asset with a horizontal line at y=0.
+
+        Example:
+            >>> from jquantstats.api import _Data
+            >>> import pandas as pd
+            >>> returns = pd.DataFrame(...)
+            >>> data = _Data(returns=returns)
+            >>> fig = data.plots.plot_returns_bars()
+            >>> fig.show()
+        """
+        # Get color palette
+        colors, _, _ = Plots._get_colors()
+
+        # Create figure
+        fig = go.Figure()
+
+        # Add a bar trace for each asset
+        for idx, col in enumerate(self.data.returns.columns):
+            fig.add_trace(
+                go.Bar(
+                    x=self.data.index,
+                    y=self.data.returns[col],
+                    name=col,
+                    marker_color=colors[idx % len(colors)],  # Cycle through colors if more assets than colors
+                )
+            )
+
+        # Update layout for better readability
+        fig.update_layout(
+            plot_bgcolor="white",
+            paper_bgcolor="white",
+            xaxis=dict(
+                tickformat="%Y",  # Format x-axis as years
+                showgrid=False,
+            ),
+            yaxis=dict(
+                tickformat=".0%",  # Format y-axis as percentages
+                showgrid=True,
+                gridcolor="lightgray",
+            ),
+        )
+
+        # Add horizontal line at y=0 to distinguish positive and negative returns
+        fig.add_hline(y=0, line=dict(color="black", width=1, dash="dash"))
+
+        return fig
+
+    def plot_snapshot(self, title="Portfolio Summary", compounded=True, log_scale=False):
+        """
+        Creates a comprehensive dashboard with multiple plots for portfolio analysis.
+
+        This function generates a three-panel plot showing:
+        1. Cumulative returns over time
+        2. Drawdowns over time
+        3. Daily returns over time
+
+        This provides a complete visual summary of portfolio performance.
+
+        Args:
+            data (_Data): A Data object containing returns data.
+            title (str, optional): Title of the plot. Defaults to "Portfolio Summary".
+            compounded (bool, optional): Whether to use compounded returns. Defaults to True.
+            log_scale (bool, optional): Whether to use logarithmic scale for cumulative returns.
+                Defaults to False.
+
+        Returns:
+            plotly.graph_objects.Figure: A Plotly figure object containing the dashboard.
+
+        Example:
+            >>> from jquantstats.api import _Data
+            >>> import pandas as pd
+            >>> returns = pd.DataFrame(...)
+            >>> data = _Data(returns=returns)
+            >>> fig = snapshot_plotly(data, title="My Portfolio Performance")
+            >>> fig.show()
+        """
+        # Calculate drawdowns
+        dd = self.data.stats.drawdown(compounded=compounded, initial=100)
+
+        # Create subplot structure
+        fig = make_subplots(
+            rows=3,
+            cols=1,
+            shared_xaxes=True,  # Share x-axis across all subplots
+            row_heights=[0.5, 0.25, 0.25],  # Allocate more space to cumulative returns
+            vertical_spacing=0.03,
+            subplot_titles=["Cumulative Return", "Drawdown", "Daily Return"],
+        )
+
+        # Plot cumulative returns for each asset
+        for col in self.data.returns.columns:
+            cum_returns = 100 * ((1 + self.data.returns[col]).cum_prod())  # Convert to percentage
+            fig.add_trace(
+                go.Scatter(
+                    x=self.data.index[self.data.index.columns[0]],
+                    y=cum_returns,
+                    name=col,
+                    mode="lines",
+                ),
+                row=1,
+                col=1,
+            )
+
+        # Plot drawdowns for each asset
+        for col in self.data.returns.columns:
+            fig.add_trace(
+                go.Scatter(
+                    x=self.data.index[self.data.index.columns[0]],
+                    y=dd[col],
+                    name=f"DD: {col}",
+                    mode="lines",
+                ),
+                row=2,
+                col=1,
+            )
+
+        # Plot daily returns for each asset
+        for col in self.data.assets:
+            fig.add_trace(
+                go.Scatter(
+                    x=self.data.index[self.data.index.columns[0]],
+                    y=self.data.all[col] * 100,  # Convert to percentage
+                    name=f"{col} Return",
+                    mode="lines",
+                ),
+                row=3,
+                col=1,
+            )
+
+        # Configure layout
+        fig.update_layout(
+            height=800,  # Taller figure for better visibility
+            title_text=title,
+            showlegend=True,
+            template="plotly_white",  # Clean white template
+            legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+        )
+
+        # Apply log scale to cumulative returns if requested
+        if log_scale:
+            fig.update_yaxes(type="log", row=1, col=1)
+
+        # Format y-axes
+        fig.update_yaxes(title="Cumulative Return (%)", row=1, col=1)
+        fig.update_yaxes(title="Drawdown", tickformat=".1%", row=2, col=1)
+        fig.update_yaxes(title="Daily Return (%)", row=3, col=1)
+
+        return fig
+
+    def monthly_heatmap(
+        self,
+        col,
+        annot_size=13,
+        cbar=True,
+        returns_label="Strategy",
+        compounded=False,
+        fontname="Arial",
+        ylabel=True,
+    ):
+        """
+        Creates a heatmap of monthly returns by year using Polars only.
+        """
+
+        cmap = "RdYlGn"
+        date_col = self.data.index.columns[0]
+
+        # Resample monthly
+        data = self.data.resample(every="1mo", compounded=compounded)
+
+        # Prepare DataFrame with Year, Month, Return (%)
+        result = data.all.with_columns(
+            pl.col(date_col).dt.year().alias("Year"),
+            pl.col(date_col).dt.month().alias("Month"),
+            (pl.col(col) * 100).alias("Return"),
+        )
+
+        # Pivot table (Year x Month)
+        pivot = result.pivot(
+            values="Return",
+            index="Year",
+            columns="Month",
+            aggregate_function="first",  # Should be fine with monthly data
+        ).sort("Year", descending=True)
+
+        # Sort columns by calendar month
+        month_cols = [str(m) for m in range(1, 13)]
+        pivot = pivot.select("Year", *month_cols)
+
+        # Rename columns to month abbreviations
+        new_col_names = ["Year"] + [calendar.month_abbr[int(m)] for m in month_cols]
+        pivot.columns = new_col_names
+
+        # Extract z-matrix for heatmap
+        z = np.round(pivot.drop("Year").to_numpy(), 2)
+        y = pivot["Year"].to_numpy().astype(str)
+        x = new_col_names[1:]
+
+        zmin = -np.nanmax(np.abs(z))
+        zmax = np.nanmax(np.abs(z))
+
+        fig = go.Figure(
+            data=go.Heatmap(
+                z=z,
+                x=x,
+                y=y,
+                text=z,
+                texttemplate="%{text:.2f}%",
+                colorscale=cmap,
+                zmid=0,
+                zmin=zmin,
+                zmax=zmax,
+                colorbar=dict(
+                    title="Return (%)",
+                    ticksuffix="%",
+                    tickfont=dict(size=annot_size),
+                )
+                if cbar
+                else None,
+                hovertemplate="Year: %{y}<br>Month: %{x}<br>Return: %{z:.2f}%",
+            )
+        )
+
+        fig.update_layout(
+            title={
+                "text": f"{returns_label} - Monthly Returns (%)",
+                "y": 0.95,
+                "x": 0.5,
+                "xanchor": "center",
+                "yanchor": "top",
+                "font": dict(family=fontname, size=16, color="black"),
+            },
+            xaxis=dict(
+                title="",
+                side="top",
+                showgrid=False,
+                tickfont=dict(family=fontname, size=annot_size),
+            ),
+            yaxis=dict(
+                title="Years" if ylabel else "",
+                autorange="reversed",
+                showgrid=False,
+                tickfont=dict(family=fontname, size=annot_size),
+            ),
+            plot_bgcolor="white",
+            paper_bgcolor="white",
+            margin=dict(l=0, r=0, t=80, b=0),
+        )
+
+        return fig

jquantstats/_stats.py

@@ -0,0 +1,450 @@
+import dataclasses
+from collections.abc import Callable
+from functools import wraps
+
+import numpy as np
+import polars as pl
+
+
+@dataclasses.dataclass(frozen=True)
+class Stats:
+    data: "_Data"  # type: ignore
+    all: pl.DataFrame = None  # Default is None; will be set in __post_init__
+
+    def __post_init__(self):
+        object.__setattr__(self, "all", self.data.all)
+
+    @staticmethod
+    def _quantile_expr(series, q):
+        return series.quantile(q)
+
+    @staticmethod
+    def _mean_positive_expr(series):
+        return series.filter(series >= 0).mean()
+
+    @staticmethod
+    def _mean_negative_expr(series):
+        return series.filter(series < 0).mean()
+
+    @staticmethod
+    def _quantile_expr(series, cutoff):
+        return series.quantile(cutoff)
+
+    @staticmethod
+    def columnwise_stat(func):
+        """
+        Decorator that applies a column-wise statistical function to all numeric columns
+        of `self.data` and returns a dictionary with keys named appropriately.
+        """
+
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            return {col: func(self, self.all[col], *args, **kwargs) for col in self.data.assets}
+
+        return wrapper
+
+    @staticmethod
+    def to_frame(func: Callable) -> Callable:
+        """Decorator: Applies per-column expressions and evaluates with .with_columns(...)"""
+
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            return self.all.select(
+                [pl.col(name) for name in self.data.date_col]
+                + [func(self, pl.col(name), *args, **kwargs).alias(name) for name in self.data.assets]
+            )
+
+        return wrapper
+
+    @columnwise_stat
+    def skew(self, series):
+        """
+        Calculates skewness (asymmetry) for each numeric column.
+        """
+        return series.skew(bias=False)
+
+    @columnwise_stat
+    def kurtosis(self, series):
+        """
+        Calculates returns' kurtosis
+        (the degree to which a distribution peak compared to a normal distribution)
+        """
+        return series.kurtosis(bias=False)
+
+    @columnwise_stat
+    def avg_return(self, series):
+        """Average return per non-zero, non-null value."""
+        return series.filter(series.is_not_null() & (series != 0)).mean()
+
+    @columnwise_stat
+    def avg_win(self, series):
+        """
+        Calculates the average winning
+        return/trade for an asset
+        """
+        return self._mean_positive_expr(series)
+
+    @columnwise_stat
+    def avg_loss(self, series):
+        """
+        Calculates the average low if
+        return/trade return for a period
+        """
+        return self._mean_negative_expr(series)
+
+    @columnwise_stat
+    def volatility(self, series, periods=252, annualize=True):
+        """
+        Calculates the volatility of returns:
+        - Std dev of returns
+        - Annualized by sqrt(periods) if `annualize` is True
+        """
+        factor = np.sqrt(periods) if annualize else 1
+        return series.std() * factor
+
+    @to_frame
+    def rolling_volatility(self, series: pl.Expr, rolling_period=126, periods_per_year=252) -> pl.Expr:
+        return series.rolling_std(window_size=rolling_period) * np.sqrt(periods_per_year)
+
+    @to_frame
+    def price(self, series: pl.Expr, compounded=False, initial=1.0) -> pl.Expr:
+        if compounded:
+            # First compute cumulative compounded returns
+            cum = initial * (1 + series).cum_prod()
+        else:
+            # Simple cumulative sum of returns
+            cum = initial + series.cum_sum()
+
+        return cum
+
+    @to_frame
+    def drawdown(self, series: pl.Expr, compounded=False, initial=1.0) -> pl.Expr:
+        """
+        Computes drawdown from the high-water mark.
+
+        Args:
+            series (pl.Expr): Polars expression for the return series.
+            compounded (bool): Whether to use compounded returns.
+            initial (float): Initial portfolio value (default is 1).
+
+        Returns:
+            pl.Expr: A Polars expression representing the drawdown.
+        """
+        if compounded:
+            # First compute cumulative compounded returns
+            equity = initial * (1 + series).cum_prod()
+        else:
+            # Simple cumulative sum of returns
+            equity = initial + series.cum_sum()
+
+        # equity = self.price(series, compounded, initial=initial)
+        return -100 * ((equity / equity.cum_max()) - 1)
+
+    @columnwise_stat
+    def autocorr(self, series: pl.Series):
+        """
+        Metric to account for autocorrelation.
+        Applies autocorrelation penalty to each numeric series (column).
+        """
+        corr = pl.corr(series, series.shift(1)).cast(pl.Float64)
+        return corr
+
+    @columnwise_stat
+    def payoff_ratio(self, series):
+        """
+        Measures the payoff ratio: average win / abs(average loss).
+        """
+        avg_win = series.filter(series > 0).mean()
+        # avg_win = self.avg_win(series)
+        avg_loss = np.abs(series.filter(series < 0).mean())
+        return avg_win / avg_loss
+
+    def win_loss_ratio(self):
+        """Shorthand for payoff_ratio()"""
+        return self.payoff_ratio()
+
+    @columnwise_stat
+    def profit_ratio(self, series):
+        """Measures the profit ratio (win ratio / loss ratio)"""
+        wins = series.filter(series > 0)
+        losses = series.filter(series < 0)
+
+        try:
+            win_ratio = np.abs(wins.mean() / wins.count())
+            loss_ratio = np.abs(losses.mean() / losses.count())
+
+            return win_ratio / loss_ratio
+
+        except TypeError:
+            return np.nan
+
+    @columnwise_stat
+    def profit_factor(self, series):
+        """Measures the profit ratio (wins / loss)"""
+        wins = series.filter(series > 0)
+        losses = series.filter(series < 0)
+
+        return np.abs(wins.sum() / losses.sum())
+
+    def common_sense_ratio(self):
+        """Measures the common sense ratio (profit factor * tail ratio)"""
+        profit_factor = self.profit_factor()
+        tail_ratio = self.tail_ratio()
+
+        return {name: profit_factor[name] * tail_ratio[name] for name in profit_factor.keys()}
+
+    @columnwise_stat
+    def value_at_risk(self, series: pl.Series, alpha: float = 0.05):
+        """
+        Calculates the daily value-at-risk
+        (variance-covariance calculation with confidence level)
+        """
+        # Ensure returns are sorted and drop nulls
+        cleaned_returns = series.drop_nulls()
+
+        # Compute VaR using quantile; note that VaR is typically a negative number (i.e. loss)
+        return cleaned_returns.quantile(alpha, interpolation="nearest")
+
+    def var(self, alpha: float = 0.05):
+        """Shorthand for value_at_risk()"""
+        return self.value_at_risk(alpha)
+
+    @columnwise_stat
+    def conditional_value_at_risk(self, series, alpha=0.05):
+        """
+        Calculates the conditional value-at-risk (CVaR / expected shortfall)
+        for each numeric column.
+        """
+        # Ensure returns are sorted and drop nulls
+        cleaned_returns = series.drop_nulls()
+
+        # Compute VaR using quantile; note that VaR is typically a negative number (i.e. loss)
+        var = cleaned_returns.quantile(alpha, interpolation="nearest")
+
+        # Compute mean of returns less than or equal to VaR
+        cvar = cleaned_returns.filter(cleaned_returns <= var).mean()
+
+        return cvar
+
+        # Compute CVaR: mean of values less than the VaR threshold
+        # return pl.when(series < var_expr).then(series).otherwise(None).mean()
+
+    def cvar(self, alpha=0.05):
+        """Shorthand for conditional_value_at_risk()"""
+        return self.conditional_value_at_risk(alpha)
+
+    def expected_shortfall(self, alpha=0.05):
+        """Shorthand for conditional_value_at_risk()"""
+        return self.conditional_value_at_risk(alpha)
+
+    @columnwise_stat
+    def tail_ratio(self, series, cutoff=0.95):
+        """Calculates the ratio of the right (95%) and left (5%) tails."""
+        left_tail = self._quantile_expr(series, 1 - cutoff)
+        right_tail = self._quantile_expr(series, cutoff)
+        return abs(right_tail / left_tail)  # .alias(series.meta.output_name)
+
+    @columnwise_stat
+    def win_rate(self, series):
+        """Calculates the win ratio for a period."""
+        num_pos = series.filter(series > 0).count()
+        num_nonzero = series.filter(series != 0).count()
+        return num_pos / num_nonzero
+
+    @columnwise_stat
+    def gain_to_pain_ratio(self, series):
+        """
+        Jack Schwager's Gain-to-Pain Ratio:
+        total return / sum of losses (in absolute value).
+        """
+        total_gain = series.sum()
+        total_pain = series.filter(series < 0).abs().sum()
+        try:
+            return total_gain / total_pain
+        except ZeroDivisionError:
+            return np.nan
+
+    @columnwise_stat
+    def outlier_win_ratio(self, series: pl.Series, quantile: float = 0.99):
+        """
+        Calculates the outlier winners ratio:
+        99th percentile of returns / mean positive return
+        """
+        q = series.quantile(quantile, interpolation="nearest")
+        mean_positive = series.filter(series > 0).mean()
+        return q / mean_positive
+
+    @columnwise_stat
+    def outlier_loss_ratio(self, series: pl.Series, quantile: float = 0.01):
+        """
+        Calculates the outlier losers ratio
+        1st percentile of returns / mean negative return
+        """
+        q = series.quantile(quantile, interpolation="nearest")
+        mean_negative = series.filter(series < 0).mean()
+        return q / mean_negative
+
+    @columnwise_stat
+    def risk_return_ratio(self, series):
+        """
+        Calculates the return/risk ratio (Sharpe ratio w/o risk-free rate).
+        """
+        return series.mean() / series.std()
+
+    def kelly_criterion(self):
+        """
+        Calculates the optimal capital allocation (Kelly Criterion) per column:
+        f* = [(b * p) - q] / b
+        where:
+          - b = payoff ratio
+          - p = win rate
+          - q = 1 - p
+        """
+        b = self.payoff_ratio()
+        p = self.win_rate()
+
+        return {
+            col: ((b[col] * p[col]) - (1 - p[col])) / b[col]
+            # if b[col] not in (None, 0) and p[col] is not None else None
+            for col in b
+        }
+
+    @columnwise_stat
+    def best(self, series):
+        """Returns the maximum return per column (best period)."""
+        return series.max()  # .alias(series.meta.output_name)
+
+    @columnwise_stat
+    def worst(self, series):
+        """Returns the minimum return per column (worst period)."""
+        return series.min()  # .alias(series.meta.output_name)
+
+    @columnwise_stat
+    def exposure(self, series):
+        """Returns the market exposure time (returns != 0)"""
+        return np.round((series.filter(series != 0).count() / self.all.height), decimals=2)
+
+    @columnwise_stat
+    def sharpe(self, series, periods=252):
+        """
+        Calculates the Sharpe ratio of asset returns.
+        """
+        divisor = series.std(ddof=1)
+
+        res = series.mean() / divisor
+        factor = periods or 1
+        return res * np.sqrt(factor)
+
+    @to_frame
+    def rolling_sharpe(self, series: pl.Expr, rolling_period=126, periods_per_year=252) -> pl.Expr:
+        res = series.rolling_mean(window_size=rolling_period) / series.rolling_std(window_size=rolling_period)
+        factor = periods_per_year or 1
+        return res * np.sqrt(factor)
+
+    @columnwise_stat
+    def sortino(self, series: pl.Series, periods=252):
+        """
+        Calculates the Sortino ratio: mean return divided by downside deviation.
+        Based on Red Rock Capital's Sortino ratio paper.
+        """
+
+        downside_deviation = np.sqrt(((series.filter(series < 0)) ** 2).mean())
+
+        ratio = series.mean() / downside_deviation
+        return ratio * np.sqrt(periods)
+
+    @to_frame
+    def rolling_sortino(self, series, rolling_period=126, periods_per_year=252):
+        mean_ret = series.rolling_mean(window_size=rolling_period)
+
+        # Rolling downside deviation (squared negative returns averaged over window)
+        downside = series.map_elements(lambda x: x**2 if x < 0 else 0.0).rolling_mean(window_size=rolling_period)
+
+        # Avoid division by zero
+        sortino = mean_ret / downside.sqrt().fill_nan(0).fill_null(0)
+        return sortino * (periods_per_year**0.5)
+
+    def adjusted_sortino(self, periods=252):
+        """
+        Jack Schwager's adjusted Sortino ratio for direct comparison to Sharpe.
+        See: https://archive.is/wip/2rwFW
+        """
+        sortino_data = self.sortino(periods=periods)
+        return {k: v / np.sqrt(2) for k, v in sortino_data.items()}
+
+    @columnwise_stat
+    def r_squared(self, series, benchmark=None):
+        """Measures the straight line fit of the equity curve"""
+        if self.data.benchmark is None:
+            raise AttributeError("No benchmark data available")
+
+        benchmark_col = benchmark or self.data.benchmark.columns[0]
+
+        # if self.data.benchmark is None:
+        #    raise AttributeError("No benchmark data available")
+        # Evaluate both series and benchmark as Series
+        df = self.all.select([series, pl.col(benchmark_col).alias("benchmark")])
+
+        # Drop nulls
+        df = df.drop_nulls()
+        print(df)
+
+        matrix = df.to_numpy()
+        # Get actual Series
+
+        strategy_np = matrix[:, 0]
+        benchmark_np = matrix[:, 1]
+
+        corr_matrix = np.corrcoef(strategy_np, benchmark_np)
+        r = corr_matrix[0, 1]
+        return r**2
+
+    def r2(self):
+        """Shorthand for r_squared()"""
+        return self.r_squared()
+
+    @columnwise_stat
+    def information_ratio(self, series, periods_per_year=252, benchmark=None):
+        """
+        Calculates the information ratio
+        (basically the risk return ratio of the net profits)
+        """
+        benchmark_col = benchmark or self.data.benchmark.columns[0]
+
+        active = series - self.data.benchmark[benchmark_col]
+
+        mean = active.mean()
+        std = active.std()
+
+        try:
+            return (mean / std) * (periods_per_year**0.5)
+        except ZeroDivisionError:
+            return 0.0
+
+    @columnwise_stat
+    def greeks(self, series, periods_per_year=252, benchmark=None):
+        """Calculates alpha and beta of the portfolio"""
+        # find covariance
+        benchmark_col = benchmark or self.data.benchmark.columns[0]
+
+        # Evaluate both series and benchmark as Series
+        df = self.all.select([series, pl.col(benchmark_col).alias("benchmark")])
+
+        # Drop nulls
+        df = df.drop_nulls()
+        matrix = df.to_numpy()
+
+        # Get actual Series
+        strategy_np = matrix[:, 0]
+        benchmark_np = matrix[:, 1]
+
+        # 2x2 covariance matrix: [[var_strategy, cov], [cov, var_benchmark]]
+        cov_matrix = np.cov(strategy_np, benchmark_np)
+
+        cov = cov_matrix[0, 1]
+        var_benchmark = cov_matrix[1, 1]
+
+        beta = cov / var_benchmark if var_benchmark != 0 else float("nan")
+        alpha = np.mean(strategy_np) - beta * np.mean(benchmark_np)
+
+        return {"alpha": alpha * periods_per_year, "beta": beta}

jquantstats/api.py

@@ -0,0 +1,222 @@
+# QuantStats: Portfolio analytics for quants
+# https://github.com/tschm/jquantstats
+#
+# Copyright 2019-2024 Ran Aroussi
+# Copyright 2025 Thomas Schmelzer
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+QuantStats API module.
+
+This module provides the core API for the QuantStats library,
+including the Data class
+for handling financial returns data and benchmarks.
+"""
+
+import dataclasses
+
+import polars as pl
+
+from ._plots import Plots
+from ._stats import Stats
+
+
+def build_data(
+    returns: pl.DataFrame, rf: float | pl.DataFrame = 0.0, benchmark: pl.DataFrame = None, date_col: str = "Date"
+) -> "_Data":
+    """
+    Build a _Data object from returns and optional benchmark using Polars.
+
+    Parameters:
+        returns (pl.DataFrame): Financial returns.
+        rf (float | pl.DataFrame): Risk-free rate (scalar or time series).
+        benchmark (pl.DataFrame, optional): Benchmark returns.
+        date_col (str): Name of the date column.
+
+    Returns:
+        _Data: Object containing excess returns and benchmark (if any).
+    """
+
+    def subtract_risk_free(df: pl.DataFrame, rf: float | pl.DataFrame, date_col: str) -> pl.DataFrame:
+        if df is None:
+            return None
+
+        # Handle scalar rf case
+        if isinstance(rf, float):
+            rf_df = df.select([pl.col(date_col), pl.lit(rf).alias("rf")])
+        else:
+            rf_df = rf.rename({rf.columns[1]: "rf"}) if rf.columns[1] != "rf" else rf
+
+        # Join and subtract
+        df = df.join(rf_df, on=date_col, how="inner")
+        return df.select(
+            [pl.col(date_col)]
+            + [
+                (pl.col(col) - pl.col("rf")).alias(col)
+                for col in df.columns
+                if col not in {date_col, "rf"} and df.schema[col] in pl.NUMERIC_DTYPES
+            ]
+        )
+
+    # Align returns and benchmark if both provided
+    if benchmark is not None:
+        joined_dates = returns.join(benchmark, on=date_col, how="inner").select(date_col)
+        if joined_dates.is_empty():
+            raise ValueError("No overlapping dates between returns and benchmark.")
+        returns = returns.join(joined_dates, on=date_col, how="inner")
+        benchmark = benchmark.join(joined_dates, on=date_col, how="inner")
+
+    # Subtract risk-free rate
+    index = returns.select(date_col)
+    excess_returns = subtract_risk_free(returns, rf, date_col).drop(date_col)
+    excess_benchmark = subtract_risk_free(benchmark, rf, date_col).drop(date_col) if benchmark is not None else None
+
+    return _Data(returns=excess_returns, benchmark=excess_benchmark, index=index)
+
+
+@dataclasses.dataclass(frozen=True)
+class _Data:
+    """
+    A container for financial returns data and an optional benchmark.
+
+    This class provides methods for analyzing and manipulating financial returns data,
+    including converting returns to prices, calculating drawdowns, and resampling data
+    to different time periods.
+
+    Attributes:
+        returns (pd.DataFrame): DataFrame containing returns data, typically with dates as index
+                               and assets as columns.
+        #benchmark (pd.Series, optional): Series containing benchmark returns data with the same
+        #                                index as returns. Defaults to None.
+    """
+
+    returns: pl.DataFrame
+    benchmark: pl.DataFrame | None = None
+    index: pl.DataFrame | None = None
+
+    @property
+    def plots(self):
+        return Plots(self)
+
+    @property
+    def stats(self):
+        return Stats(self)
+
+    @property
+    def date_col(self):
+        return self.index.columns
+
+    @property
+    def assets(self):
+        try:
+            return self.returns.columns + self.benchmark.columns
+        except AttributeError:
+            return self.returns.columns
+
+    def __post_init__(self) -> None:
+        """
+        Validates that the benchmark index matches the returns index if benchmark is provided.
+
+        Raises:
+            AssertionError: If benchmark is provided and its index doesn't match returns index.
+        """
+
+    @property
+    def all(self) -> pl.DataFrame:
+        """
+        Combines returns and benchmark data into a single DataFrame.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing all returns data and benchmark (if available),
+                         with NaN values filled with 0.0.
+        """
+        if self.benchmark is None:
+            return pl.concat([self.index, self.returns], how="horizontal")
+        else:
+            return pl.concat([self.index, self.returns, self.benchmark], how="horizontal")
+
+    def resample(self, every: str = "1mo", compounded: bool = False) -> "_Data":
+        """
+        Resamples returns and benchmark to a different frequency using Polars.
+
+        Args:
+            every (str, optional): Resampling frequency (e.g., '1mo', '1y'). Defaults to '1mo'.
+            compounded (bool, optional): Whether to compound returns. Defaults to False.
+
+        Returns:
+            _Data: Resampled data.
+        """
+
+        def resample_frame(df: pl.DataFrame) -> pl.DataFrame:
+            if df is None:
+                return None
+
+            df = self.index.hstack(df)  # Add the date column for resampling
+
+            return df.group_by_dynamic(
+                index_column=self.index.columns[0], every=every, period=every, closed="right", label="right"
+            ).agg(
+                [
+                    pl.col(col).sum().alias(col) if not compounded else ((pl.col(col) + 1.0).product() - 1.0).alias(col)
+                    for col in df.columns
+                    if col != self.index.columns[0]
+                ]
+            )
+
+        resampled_returns = resample_frame(self.returns)
+        resampled_benchmark = resample_frame(self.benchmark) if self.benchmark is not None else None
+        resampled_index = resampled_returns.select(self.index.columns[0])
+
+        return _Data(
+            returns=resampled_returns.drop(self.index.columns[0]),
+            benchmark=resampled_benchmark.drop(self.index.columns[0]) if resampled_benchmark is not None else None,
+            index=resampled_index,
+        )
+
+    def copy(self) -> "_Data":
+        """
+        Creates a deep copy of the Data object.
+
+        Returns:
+            _Data: A new Data object with copies of the returns and benchmark.
+        """
+        try:
+            return _Data(returns=self.returns.clone(), benchmark=self.benchmark.clone(), index=self.index.clone())
+        except AttributeError:
+            # Handle case where benchmark is None
+            return _Data(returns=self.returns.clone(), index=self.index.clone())
+
+    def head(self, n: int = 5) -> "_Data":
+        """
+        Returns the first n rows of the combined returns and benchmark data.
+
+        Args:
+            n (int, optional): Number of rows to return. Defaults to 5.
+
+        Returns:
+            _Data: A new Data object containing the first n rows of the combined data.
+        """
+        return _Data(returns=self.returns.head(n), benchmark=self.benchmark.head(n), index=self.index.head(n))
+
+    def tail(self, n: int = 5) -> "_Data":
+        """
+        Returns the last n rows of the combined returns and benchmark data.
+
+        Args:
+            n (int, optional): Number of rows to return. Defaults to 5.
+
+        Returns:
+            _Data: A new Data object containing the last n rows of the combined data.
+        """
+        return _Data(returns=self.returns.tail(n), benchmark=self.benchmark.tail(n), index=self.index.tail(n))

jquantstats-0.0.2.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: jquantstats
+Version: 0.0.2
+Summary: Toying with quantstats
+Project-URL: repository, https://github.com/tschm/jquantstats
+Author-email: tschm <thomas.schmelzer@gmail.com>
+License-File: LICENSE.txt
+Requires-Python: >=3.10
+Requires-Dist: kaleido==0.2.1
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: plotly>=6.0.0
+Requires-Dist: polars==1.29.0
+Provides-Extra: dev
+Requires-Dist: pre-commit==4.2.0; extra == 'dev'
+Requires-Dist: pytest-cov==6.1.1; extra == 'dev'
+Requires-Dist: pytest==8.3.5; extra == 'dev'
+Requires-Dist: yfinance==0.2.58; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# [jQuantStats](https://tschm.github.io/jquantstats/book): Portfolio analytics for quants
+
+[![PyPI version](https://badge.fury.io/py/jquantstats.svg)](https://badge.fury.io/py/jquantstats)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE.txt)
+[![CI](https://github.com/tschm/jquantstats/actions/workflows/ci.yml/badge.svg)](https://github.com/tschm/jquantstats/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/tschm/jquantstats/badge.svg?branch=main)](https://coveralls.io/github/tschm/jquantstats?branch=main)
+[![CodeFactor](https://www.codefactor.io/repository/github/tschm/jquantstats/badge)](https://www.codefactor.io/repository/github/tschm/quantstats)
+[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://github.com/renovatebot/renovate)
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tschm/jquantstats)
+
+## Overview
+
+**jQuantStats** is a Python library for portfolio analytics
+that helps quants and portfolio managers understand
+their performance through in-depth analytics and risk metrics.
+It provides tools for calculating various performance metrics
+and visualizing portfolio performance.
+
+The library is inspired by and currently exposes a subset of the
+functionality of [QuantStats](https://github.com/ranaroussi/quantstats),
+focusing on providing a clean, modern API with enhanced
+visualization capabilities using Plotly.
+
+We have made the following changes when compared to quantstats:
+
+- added tests (based on pytest), pre-commit hooks and
+  github ci/cd workflows
+- removed a direct dependency on yfinance to inject data
+- moved all graphical output to plotly and removed the matplotlib dependency
+- removed some statistical metrics but intend to bring them back
+- moved to Marimo for demos
+- gave up on the very tight coupling with pandas
+
+Along the way we broke downwards compatibility with quantstats but the
+underlying usage pattern is too different. Users familiar with
+Dataclasses may find the chosen path appealing.
+A data class is
+constructed using the `build_data` function.
+This function is essentially
+the only viable entry point into jquantstats.
+It constructs and returns
+a `_Data` object which exposes plots and stats via its member attributes.
+
+At this early stage the user would have to define a benchmark
+and set the underlying risk-free rate.
+
+## Features
+
+- **Performance Metrics**: Calculate key metrics like Sharpe ratio, Sortino ratio,
+  drawdowns, volatility, and many more
+- **Risk Analysis**: Analyze risk through metrics like Value at Risk (VaR),
+  Conditional VaR, and drawdown analysis
+- **Visualization**: Create interactive plots for portfolio performance, drawdowns,
+  return distributions, and monthly heatmaps
+- **Benchmark Comparison**: Compare your portfolio performance against benchmarks
+
+## Installation
+
+```bash
+pip install jquantstats
+```
+
+For development:
+
+```bash
+pip install jquantstats[dev]
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from jquantstats.api import build_data
+
+# Create a Data object from returns
+returns = pd.DataFrame(...)  # Your returns data
+
+# Basic usage
+data = build_data(returns=returns)
+
+# With benchmark and risk-free rate
+benchmark = pd.Series(...)  # Your benchmark returns
+data = build_data(
+    returns=returns,
+    benchmark=benchmark,
+    rf=0.02,      # risk-free rate (e.g., 2% annual rate)
+    nperiods=252  # number of trading days per year
+)
+
+# Calculate statistics
+sharpe = data.stats.sharpe()
+volatility = data.stats.volatility()
+
+# Create visualizations
+fig = data.plots.plot_snapshot(title="Portfolio Performance")
+fig.show()
+
+# Monthly returns heatmap
+fig = data.plots.monthly_heatmap()
+fig.show()
+```
+
+## Documentation
+
+For detailed documentation,
+visit [jQuantStats Documentation](https://tschm.github.io/jquantstats/book).
+
+## Requirements
+
+- Python 3.10+
+- numpy
+- pandas
+- scipy
+- plotly
+- kaleido (for static image export)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the
+Apache License 2.0 - see the [LICENSE.txt](LICENSE.txt) file for details.

jquantstats-0.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+jquantstats/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jquantstats/_plots.py,sha256=y3hGRvw-2X9EJaCRoI2zQ7G4Ghm5rlXiORlr2h9BrkA,10077
+jquantstats/_stats.py,sha256=ftROfeBH_3AIpp-ZLAGSLEHE2XUYfdbTIWk7pGD4lOQ,15163
+jquantstats/api.py,sha256=OZ9znbQFx4qwA1oh3mEBsrXDtRpcNEHzaJ9u5N9fikA,7995
+jquantstats-0.0.2.dist-info/METADATA,sha256=eBXVpTwtADqDl97x35oD-xJAk-TPT63PCv_yjnjiEWg,5081
+jquantstats-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+jquantstats-0.0.2.dist-info/licenses/LICENSE.txt,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+jquantstats-0.0.2.dist-info/RECORD,,

jquantstats-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jquantstats-0.0.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,175 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.