finkritq 0.1.0__py3-none-any.whl

finkritq/__init__.py

@@ -0,0 +1 @@
+# finkritq/__init__.py

finkritq/__main__.py

@@ -0,0 +1,6 @@
+# finkrit/packages/finkritq/__main__.py
+"""Entry point for ``python -m finkritq``: runs the demo in main.py."""
+from finkritq.main import main
+
+if __name__ == "__main__":
+    main()

finkritq/anal/__init__.py

@@ -0,0 +1,9 @@
+# finkrit/packages/finkritq/anal/__init__.py
+"""
+Analytics: measures computed from market data.
+
+Two families live here: `risk` (how risky) and `performance` (how much it
+returned, and how good that return was for the risk taken). The raw
+prices-to-returns transform these build on is not analytics; it lives in
+finkritq.transform.
+"""

finkritq/anal/performance/__init__.py

@@ -0,0 +1,145 @@
+# finkrit/packages/finkritq/anal/performance/__init__.py
+"""
+Performance analytics: return magnitude and risk-adjusted performance.
+
+Where anal/risk answers "how risky", this package answers "how much did it
+return" and "how good was that return for the risk taken". It starts with raw
+return magnitude (total, annualized) and builds up to the risk-adjusted ratios
+(Sharpe, Sortino, Calmar, ...) that combine a return numerator with a risk
+denominator from anal/risk.
+"""
+from finkritq.anal.performance.total_return import (
+    portfolio_total_return,
+    total_return,
+    total_return_asset,
+    total_return_from_prices,
+    total_return_from_returns,
+)
+from finkritq.anal.performance.annualized_return import (
+    annualized_return,
+    annualized_return_asset,
+    annualized_return_from_prices,
+    annualized_return_from_returns,
+    portfolio_annualized_return,
+)
+from finkritq.anal.performance.sharpe_ratio import (
+    portfolio_sharpe_ratio,
+    sharpe_ratio,
+    sharpe_ratio_asset,
+    sharpe_ratio_from_prices,
+    sharpe_ratio_from_returns,
+)
+from finkritq.anal.performance.sortino_ratio import (
+    portfolio_sortino_ratio,
+    sortino_ratio,
+    sortino_ratio_asset,
+    sortino_ratio_from_prices,
+    sortino_ratio_from_returns,
+)
+from finkritq.anal.performance.calmar_ratio import (
+    calmar_ratio,
+    calmar_ratio_asset,
+    calmar_ratio_from_prices,
+    calmar_ratio_from_returns,
+    portfolio_calmar_ratio,
+)
+from finkritq.anal.performance.treynor_ratio import (
+    portfolio_treynor_ratio,
+    treynor_ratio,
+    treynor_ratio_asset,
+    treynor_ratio_from_prices,
+    treynor_ratio_from_returns,
+)
+from finkritq.anal.performance.information_ratio import (
+    information_ratio,
+    information_ratio_asset,
+    information_ratio_from_prices,
+    information_ratio_from_returns,
+    portfolio_information_ratio,
+)
+from finkritq.anal.performance.jensens_alpha import (
+    jensens_alpha,
+    jensens_alpha_asset,
+    jensens_alpha_from_prices,
+    jensens_alpha_from_returns,
+    portfolio_jensens_alpha,
+)
+from finkritq.anal.performance.flows import (
+    money_weighted_return,
+    time_weighted_return,
+)
+from finkritq.anal.performance.attribution import (
+    AttributionResult,
+    SegmentAttribution,
+    brinson_attribution,
+)
+from finkritq.anal.performance.contribution import (
+    Contribution,
+    contribution_to_return,
+)
+from finkritq.anal.performance.fees import (
+    net_of_fees,
+)
+
+__all__ = [
+    # total (cumulative) return
+    "total_return_from_returns",
+    "total_return_from_prices",
+    "total_return",
+    "total_return_asset",
+    "portfolio_total_return",
+    # annualized (geometric / CAGR) return
+    "annualized_return_from_returns",
+    "annualized_return_from_prices",
+    "annualized_return",
+    "annualized_return_asset",
+    "portfolio_annualized_return",
+    # sharpe ratio
+    "sharpe_ratio_from_returns",
+    "sharpe_ratio_from_prices",
+    "sharpe_ratio",
+    "sharpe_ratio_asset",
+    "portfolio_sharpe_ratio",
+    # sortino ratio
+    "sortino_ratio_from_returns",
+    "sortino_ratio_from_prices",
+    "sortino_ratio",
+    "sortino_ratio_asset",
+    "portfolio_sortino_ratio",
+    # calmar ratio
+    "calmar_ratio_from_returns",
+    "calmar_ratio_from_prices",
+    "calmar_ratio",
+    "calmar_ratio_asset",
+    "portfolio_calmar_ratio",
+    # treynor ratio
+    "treynor_ratio_from_returns",
+    "treynor_ratio_from_prices",
+    "treynor_ratio",
+    "treynor_ratio_asset",
+    "portfolio_treynor_ratio",
+    # information ratio
+    "information_ratio_from_returns",
+    "information_ratio_from_prices",
+    "information_ratio",
+    "information_ratio_asset",
+    "portfolio_information_ratio",
+    # jensen's alpha
+    "jensens_alpha_from_returns",
+    "jensens_alpha_from_prices",
+    "jensens_alpha",
+    "jensens_alpha_asset",
+    "portfolio_jensens_alpha",
+    # cash-flow-aware returns
+    "time_weighted_return",
+    "money_weighted_return",
+    # attribution
+    "brinson_attribution",
+    "AttributionResult",
+    "SegmentAttribution",
+    # contribution to return
+    "contribution_to_return",
+    "Contribution",
+    # fees
+    "net_of_fees",
+]

finkritq/anal/performance/annualized_return.py

@@ -0,0 +1,135 @@
+# finkrit/packages/finkritq/anal/performance/annualized_return.py
+"""
+Annualized return (CAGR): the constant per-year growth rate that compounds to the
+window's total return. A 21% gain over two years is not 10.5%/yr, it is
+(1.21)^(1/2) - 1 = 10%/yr, because growth compounds.
+
+This is the geometric annualized return, the "how fast did it actually grow per
+year" figure. It is the numerator every risk-adjusted ratio (Sharpe, Sortino,
+Calmar, ...) will scale against. It builds directly on total_return.
+"""
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+import numpy as np
+from numpy.typing import NDArray
+
+from finkritq.anal.performance.total_return import (
+    portfolio_total_return,
+    total_return_from_prices,
+    total_return_from_returns,
+)
+from finkritq.asset import Asset
+from finkritq.data import DataRegistry
+from finkritq.datatype import PriceHistory, ReturnCalculationMethod, WeightingBasis
+from finkritq.portfolio import PortfolioData
+
+
+def _annualize(total_return: float, n_periods: int, periods_per_year: int) -> float:
+    """
+    Scale a window's total return to a constant per-year (geometric) rate.
+
+    `n_periods` is the number of return periods (compounding intervals), NOT the
+    number of price observations. `periods_per_year` says how many of those
+    intervals make a year (252 trading days, 12 months, ...), so the window spans
+    n_periods / periods_per_year years and:
+
+        annualized = (1 + total_return) ** (1 / years) - 1
+
+    A window shorter than one year is extrapolated to a full year (the exponent
+    exceeds 1), which is standard but makes short-window figures volatile.
+    """
+
+    if n_periods <= 0:
+        # No elapsed periods, so no growth rate to speak of.
+        return 0.0
+
+    base = 1.0 + total_return
+    if base <= 0.0:
+        # Wealth reached zero (or a nonsensical negative). A fractional power of a
+        # non-positive base is not real, and total loss annualizes to -100%.
+        return -1.0
+
+    years = n_periods / periods_per_year
+    return float(base ** (1.0 / years) - 1.0)
+
+
+def annualized_return_from_returns(
+    returns: NDArray[np.float64],
+    method: ReturnCalculationMethod = ReturnCalculationMethod.LOG,
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Annualized (geometric) return from a periodic return series.
+
+    `method` states how the series compounds (see total_return_from_returns). The
+    period count is len(returns), one compounding interval per element.
+    """
+
+    total = total_return_from_returns(returns, method=method)
+    return _annualize(total, len(returns), periods_per_year)
+
+
+def annualized_return_from_prices(
+    prices: NDArray[np.float64],
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Annualized (geometric) return from a price series.
+
+    No `method`: total return from prices is the convention-free endpoint ratio.
+    m prices span m - 1 intervals, so that is the period count.
+    """
+
+    total = total_return_from_prices(prices)
+    return _annualize(total, len(prices) - 1, periods_per_year)
+
+
+def annualized_return(
+    history: PriceHistory,
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Annualized (geometric) return from a PriceHistory.
+    """
+
+    return annualized_return_from_prices(history.close, periods_per_year=periods_per_year)
+
+
+def annualized_return_asset(
+    asset: Asset,
+    registry: DataRegistry,
+    start: date | None = None,
+    end: date | None = None,
+    interval: str = "1d",
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Annualized (geometric) return directly from an asset.
+    """
+
+    end = end or date.today()
+    start = start or end - timedelta(days=365)
+
+    history = registry.history(asset, start=start, end=end, interval=interval)
+
+    return annualized_return(history, periods_per_year=periods_per_year)
+
+
+def portfolio_annualized_return(
+    portfolio_data: PortfolioData,
+    basis: WeightingBasis = WeightingBasis.BUY_AND_HOLD,
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Annualized (geometric) return of a portfolio.
+
+    `basis` selects which portfolio total return is annualized (see
+    portfolio_total_return / WeightingBasis). Both bases share the same period
+    count: the number of return intervals over the window, n_periods - 1.
+    """
+
+    total = portfolio_total_return(portfolio_data, basis=basis)
+    return _annualize(total, portfolio_data.n_periods - 1, periods_per_year)
+

finkritq/anal/performance/attribution.py

@@ -0,0 +1,98 @@
+# finkrit/packages/finkritq/anal/performance/attribution.py
+"""
+Brinson performance attribution (aka "return decomposition"), splitting a
+portfolio's active return (portfolio minus benchmark) into the decisions that
+produced it.
+
+The classic Brinson-Hood-Beebower decomposition, per segment i (an asset, sector,
+or asset class):
+
+  allocation_i  = (w_p_i - w_b_i) * R_b_i           (over/underweighting segments)
+  selection_i   =  w_b_i * (R_p_i - R_b_i)          (picking within a segment)
+  interaction_i = (w_p_i - w_b_i) * (R_p_i - R_b_i) (the cross term)
+
+Summed across segments these equal the total active return R_p - R_b exactly, so
+the attribution always reconciles. Weights and segment returns are the inputs.
+Where the segments come from (assets, GICS sectors, asset classes) is the caller's
+choice.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Hashable
+
+
+@dataclass(frozen=True, slots=True)
+class SegmentAttribution:
+    segment: Hashable
+    allocation: float
+    selection: float
+    interaction: float
+
+    @property
+    def total(self) -> float:
+        return self.allocation + self.selection + self.interaction
+
+
+@dataclass(frozen=True, slots=True)
+class AttributionResult:
+    segments: list[SegmentAttribution]
+    allocation: float
+    selection: float
+    interaction: float
+    active_return: float          # portfolio return - benchmark return
+
+    @property
+    def total(self) -> float:
+        return self.allocation + self.selection + self.interaction
+
+
+def brinson_attribution(
+    portfolio_weights: dict[Hashable, float],
+    benchmark_weights: dict[Hashable, float],
+    portfolio_returns: dict[Hashable, float],
+    benchmark_returns: dict[Hashable, float],
+) -> AttributionResult:
+    """
+    Decompose active return into allocation, selection, and interaction by segment.
+
+    All four dicts are keyed by segment. A segment missing from a dict contributes
+    0 for that term. The per-segment effects sum to the total active return, so
+    ``result.total`` equals ``result.active_return`` up to floating point.
+    """
+    segments = (
+        set(portfolio_weights) | set(benchmark_weights)
+        | set(portfolio_returns) | set(benchmark_returns)
+    )
+
+    per_segment: list[SegmentAttribution] = []
+    total_alloc = total_sel = total_inter = 0.0
+    portfolio_return = 0.0
+    benchmark_return = 0.0
+
+    for segment in segments:
+        wp = portfolio_weights.get(segment, 0.0)
+        wb = benchmark_weights.get(segment, 0.0)
+        rp = portfolio_returns.get(segment, 0.0)
+        rb = benchmark_returns.get(segment, 0.0)
+
+        allocation = (wp - wb) * rb
+        selection = wb * (rp - rb)
+        interaction = (wp - wb) * (rp - rb)
+
+        per_segment.append(SegmentAttribution(segment, allocation, selection, interaction))
+        total_alloc += allocation
+        total_sel += selection
+        total_inter += interaction
+        portfolio_return += wp * rp
+        benchmark_return += wb * rb
+
+    return AttributionResult(
+        segments=per_segment,
+        allocation=total_alloc,
+        selection=total_sel,
+        interaction=total_inter,
+        active_return=portfolio_return - benchmark_return,
+    )
+
+

finkritq/anal/performance/calmar_ratio.py

@@ -0,0 +1,142 @@
+# finkritq/anal/performance/calmar_ratio.py
+"""
+Calmar ratio: annualized return per unit of worst peak-to-trough loss.
+
+    calmar = annualized return / |maximum drawdown|
+
+Where Sharpe and Sortino divide by a dispersion measure, Calmar divides by the
+single worst drawdown, so it speaks to pain tolerance: how much growth did you
+earn for the deepest loss you had to sit through. Standard Calmar takes no
+risk-free rate.
+"""
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+import numpy as np
+from numpy.typing import NDArray
+
+from finkritq.anal.performance.annualized_return import (
+    annualized_return_from_prices,
+    annualized_return_from_returns,
+    portfolio_annualized_return,
+)
+from finkritq.anal.risk.drawdown import (
+    maximum_drawdown_from_prices,
+    portfolio_maximum_drawdown,
+)
+from finkritq.asset import Asset
+from finkritq.data import DataRegistry
+from finkritq.datatype import PriceHistory, ReturnCalculationMethod, WeightingBasis
+from finkritq.portfolio import PortfolioData
+
+
+def _calmar(annualized_return: float, maximum_drawdown: float) -> float:
+    """
+    Combine the annualized return with the maximum drawdown.
+
+    `maximum_drawdown` is non-positive (a drawdown of -0.2 is a 20% loss). Returns
+    nan when it is exactly zero: a series that never fell has no drawdown to
+    divide by and the ratio is undefined.
+    """
+
+    if maximum_drawdown == 0.0:
+        return float("nan")
+
+    return annualized_return / abs(maximum_drawdown)
+
+
+def calmar_ratio_from_returns(
+    returns: NDArray[np.float64],
+    method: ReturnCalculationMethod = ReturnCalculationMethod.LOG,
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Calmar ratio from a periodic return series.
+
+    The wealth path is reconstructed here (rather than via
+    maximum_drawdown_from_returns, which is simple-only) so it can honor `method`:
+    exp of the cumulative sum for log returns, cumulative product for simple. A
+    leading 1.0 is prepended so a first-period loss counts. With that, this
+    matches calmar_ratio_from_prices exactly (drawdown is scale-invariant).
+    """
+
+    annualized = annualized_return_from_returns(
+        returns, method=method, periods_per_year=periods_per_year
+    )
+
+    if method == ReturnCalculationMethod.LOG:
+        wealth = np.concatenate(([1.0], np.exp(np.cumsum(returns))))
+    else:
+        wealth = np.concatenate(([1.0], np.cumprod(1.0 + returns)))
+
+    return _calmar(annualized, maximum_drawdown_from_prices(wealth))
+
+
+def calmar_ratio_from_prices(
+    prices: NDArray[np.float64],
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Calmar ratio from a price series.
+
+    No `method`: both the annualized return and the drawdown are level-based and
+    convention-free.
+    """
+
+    annualized = annualized_return_from_prices(prices, periods_per_year=periods_per_year)
+
+    return _calmar(annualized, maximum_drawdown_from_prices(prices))
+
+
+def calmar_ratio(
+    history: PriceHistory,
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Calmar ratio from a PriceHistory.
+    """
+
+    return calmar_ratio_from_prices(history.close, periods_per_year=periods_per_year)
+
+
+def calmar_ratio_asset(
+    asset: Asset,
+    registry: DataRegistry,
+    start: date | None = None,
+    end: date | None = None,
+    interval: str = "1d",
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Calmar ratio directly from an asset.
+    """
+
+    end = end or date.today()
+    start = start or end - timedelta(days=365)
+
+    history = registry.history(asset, start=start, end=end, interval=interval)
+
+    return calmar_ratio(history, periods_per_year=periods_per_year)
+
+
+def portfolio_calmar_ratio(
+    portfolio_data: PortfolioData,
+    basis: WeightingBasis = WeightingBasis.BUY_AND_HOLD,
+    periods_per_year: int = 252,
+) -> float:
+    """
+    Calmar ratio of a portfolio.
+
+    `basis` is passed to BOTH the annualized return and the maximum drawdown, so
+    the ratio describes one portfolio (see WeightingBasis). Defaults to
+    BUY_AND_HOLD, the realized return over the realized worst drawdown.
+    """
+
+    annualized = portfolio_annualized_return(
+        portfolio_data, basis=basis, periods_per_year=periods_per_year
+    )
+    max_dd = portfolio_maximum_drawdown(portfolio_data, basis=basis)
+
+    return _calmar(annualized, max_dd)
+

finkritq/anal/performance/contribution.py

@@ -0,0 +1,55 @@
+# finkrit/packages/finkritq/anal/performance/contribution.py
+"""
+Contribution to return: how much each holding added to or subtracted from the
+portfolio's total return over the window, the "top contributors and detractors"
+line every performance report carries.
+
+This is the plain-language companion to attribution. Attribution is
+benchmark-relative (allocation vs selection), contribution is absolute: on a
+buy-and-hold basis each holding's contribution is its START weight times its own
+total return, and those pieces sum exactly to the portfolio's total return (the
+value path holds today's share counts fixed, so there is no rebalancing term to
+reconcile). Rank them and the ends of the list are the contributors and
+detractors.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from finkritq.asset import Asset
+from finkritq.portfolio import PortfolioData
+
+
+@dataclass(frozen=True, slots=True)
+class Contribution:
+    """One holding's contribution to the portfolio's total return."""
+
+    asset: Asset
+    start_weight: float     # weight at the start of the window
+    asset_return: float     # the asset's own total return over the window
+    contribution: float     # start_weight * asset_return
+
+
+def contribution_to_return(portfolio_data: PortfolioData) -> list[Contribution]:
+    """
+    Each holding's contribution to total return, ranked best first.
+
+    ``contribution = start_weight * asset_return``. Summed across holdings this
+    equals the portfolio's total return over the window. The first entries are the
+    top contributors, the last are the detractors.
+    """
+    start_weights = portfolio_data.start_weights
+
+    contributions: list[Contribution] = []
+    for asset, weight in start_weights.items():
+        close = portfolio_data[asset].close
+        asset_return = float(close[-1] / close[0] - 1.0)
+        contributions.append(Contribution(
+            asset=asset,
+            start_weight=weight,
+            asset_return=asset_return,
+            contribution=weight * asset_return,
+        ))
+
+    contributions.sort(key=lambda item: item.contribution, reverse=True)
+    return contributions

finkritq/anal/performance/fees.py

@@ -0,0 +1,28 @@
+# finkrit/packages/finkritq/anal/performance/fees.py
+"""
+Gross-to-net return: reduce a return by the management fee, the net-of-fees figure
+every performance report shows alongside the gross.
+
+finq only does the math. A flat annual fee rate is applied as a haircut on value,
+net = (1 + gross) * (1 - annual_fee_rate) ** years - 1, which treats the fee as a
+fraction of value taken each year. This ignores intra-year timing and tiered
+schedules, the actual fee schedule assigned to an owner lives above finq, only the
+rate and the horizon come in here.
+"""
+from __future__ import annotations
+
+
+def net_of_fees(gross_return: float, annual_fee_rate: float, years: float = 1.0) -> float:
+    """
+    Net-of-fees return from a gross return over ``years`` at ``annual_fee_rate``.
+
+    The fee compounds as an annual haircut on value, so for a 1-year period
+    net is approximately ``gross - fee``, and over multiple years the fee
+    compounds like a negative return.
+    """
+    if not 0.0 <= annual_fee_rate < 1.0:
+        raise ValueError("annual_fee_rate must be in [0, 1).")
+    if years < 0.0:
+        raise ValueError("years must be non-negative.")
+    fee_factor = (1.0 - annual_fee_rate) ** years
+    return (1.0 + gross_return) * fee_factor - 1.0