portpy-quant 0.1.0__py3-none-any.whl

portpy/__init__.py

@@ -0,0 +1,50 @@
+"""
+PortPy: portfolio analysis, optimization, and management.
+
+The main entry point is :class:`Portfolio`. Every metric/chart/model/strategy
+can explain itself in plain language - call `.explain()` on a result, or
+`portpy.explain("name")` directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import portpy.explain as explain_module
+from portpy import core, metrics
+from portpy.explain import Explanation, MetricResult, available, get, register
+from portpy.portfolio import Portfolio
+
+__version__ = "0.1.0"
+
+
+class _ExplainAPI:
+    """Callable explain facade that also exposes registry helpers."""
+
+    def __call__(self, obj: Any, *, value: Any = None, print_it: bool = True) -> str:
+        return explain_module.explain(obj, value=value, print_it=print_it)
+
+    def available(self, category: str | None = None) -> list[str]:
+        return explain_module.available(category)
+
+    def get(self, name: str) -> Explanation:
+        return explain_module.get(name)
+
+    def register(self, explanation: Explanation) -> Explanation:
+        return explain_module.register(explanation)
+
+
+explain = _ExplainAPI()
+
+__all__ = [
+    "Portfolio",
+    "explain",
+    "Explanation",
+    "MetricResult",
+    "available",
+    "get",
+    "register",
+    "core",
+    "metrics",
+    "__version__",
+]

portpy/core/__init__.py

@@ -0,0 +1,19 @@
+"""
+Core building blocks: asset tagging, weights, calendar alignment, currency conversion.
+"""
+
+from portpy.core.asset import ALWAYS_ON_CLASSES, AssetClass
+from portpy.core.calendar import align_calendars, calendar_coverage_report, detect_frequency
+from portpy.core.currency import convert_to_base_currency
+from portpy.core.weights import equal_weights, normalize_weights
+
+__all__ = [
+    "AssetClass",
+    "ALWAYS_ON_CLASSES",
+    "align_calendars",
+    "calendar_coverage_report",
+    "detect_frequency",
+    "convert_to_base_currency",
+    "equal_weights",
+    "normalize_weights",
+]

portpy/core/asset.py

@@ -0,0 +1,32 @@
+"""
+Lightweight asset tagging, used only for reporting/grouping, but never required.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AssetClass(str, Enum):
+    """
+    Optional tag for an asset's broad class.
+
+    Passing these to :class:`~portpy.portfolio.Portfolio` (via ``asset_classes=``)
+    is purely informational - it powers grouping in tearsheets and reminds you which
+    assets trade around the clock (crypto) vs. only on business days (equities,
+    bonds), but PortPy never uses it to silently reindex or fill your data.
+    """
+
+    EQUITY = "equity"
+    CRYPTO = "crypto"
+    BOND = "bond"
+    COMMODITY = "commodity"
+    FX = "fx"
+    REAL_ESTATE = "real_estate"
+    OTHER = "other"
+
+
+"""
+Asset classes that typically trade 24/7 - useful when choosing a calendar-alignment method.
+"""
+ALWAYS_ON_CLASSES = frozenset({AssetClass.CRYPTO, AssetClass.FX})

portpy/core/calendar.py

@@ -0,0 +1,110 @@
+"""
+Calendar-alignment helpers for combining assets with different trading calendars.
+
+PortPy's `Portfolio` never aligns or fills data for you (see the package README) -
+if you build a DataFrame from, say, Bitcoin (trades every day) and a stock (trades
+Mon-Fri), the stock's columns will have NaNs on weekends. Call one of these
+functions *before* constructing a `Portfolio` to resolve that deliberately, rather
+than accidentally.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+_METHODS = ("intersection", "ffill_union", "business_days")
+
+
+def detect_frequency(index: pd.DatetimeIndex) -> str:
+    """
+    Roughly classify a DatetimeIndex's spacing (informational only).
+
+    Returns one of: "daily-7" (includes weekends, e.g. crypto), "daily-5" (business
+    days, e.g. equities/bonds), "weekly", "monthly", "irregular", or "unknown" (too
+    few points to tell).
+    """
+    if len(index) < 3:
+        return "unknown"
+    diffs = pd.Series(index).diff().dropna().dt.days
+    median = diffs.median()
+    if median <= 1.5:
+        weekdays = pd.Index(index).dayofweek
+        has_weekend = bool(((weekdays == 5) | (weekdays == 6)).any())
+        return "daily-7" if has_weekend else "daily-5"
+    if median <= 4:
+        return "weekly"
+    if median <= 10:
+        return "biweekly"
+    if median <= 35:
+        return "monthly"
+    return "irregular"
+
+
+def align_calendars(
+    prices: dict[str, pd.Series] | pd.DataFrame,
+    method: str = "intersection",
+) -> pd.DataFrame:
+    """
+    Combine assets that trade on different calendars into one aligned DataFrame.
+
+    Args:
+        prices: Either a dict of ``{asset_name: price_series}`` or an already-
+            combined DataFrame (columns = assets) that may contain NaNs from
+            mismatched calendars.
+        method: One of:
+
+            - ``"intersection"``: keep only dates where *every* asset has a price
+              (drops all weekend/holiday rows if any asset is business-days-only).
+              Use this to analyze on the slowest asset's calendar (e.g. equities).
+            - ``"ffill_union"``: take the union of all dates, forward-fill gaps
+              (e.g. carries Friday's stock close through the weekend), then drop
+              any remaining leading NaNs. Use this to keep crypto's 24/7 calendar
+              while still pricing equities every day.
+            - ``"business_days"``: reindex everything onto a Mon-Fri business-day
+              calendar, forward-filling gaps, then drop remaining leading NaNs.
+              Use this to standardize on the equity/bond calendar even if the
+              combined frame currently has 7-day-a-week rows.
+
+    Returns:
+        A DataFrame with no NaNs, ready to pass to
+        :class:`~portpy.portfolio.Portfolio`.
+    """
+    if method not in _METHODS:
+        raise ValueError(f"method must be one of {_METHODS}, got {method!r}.")
+
+    if isinstance(prices, dict):
+        df = pd.concat(prices, axis=1)
+    else:
+        df = prices.copy()
+    df = df.sort_index()
+
+    if method == "intersection":
+        return df.dropna(how="any")
+    if method == "ffill_union":
+        return df.ffill().dropna(how="any")
+    # business_days
+    bdays = pd.bdate_range(df.index.min(), df.index.max())
+    return df.reindex(bdays).ffill().dropna(how="any")
+
+
+def calendar_coverage_report(prices: pd.DataFrame) -> pd.DataFrame:
+    """
+    Per-asset diagnostic: detected frequency, date range, and NaN count.
+
+    Run this before choosing an `align_calendars` method - it tells you which
+    assets are actually mismatched and by how much.
+    """
+    rows = []
+    for col in prices.columns:
+        s = prices[col].dropna()
+        rows.append(
+            {
+                "asset": col,
+                "frequency": detect_frequency(pd.DatetimeIndex(s.index)),
+                "first_date": s.index.min() if len(s) else pd.NaT,
+                "last_date": s.index.max() if len(s) else pd.NaT,
+                "n_observations": len(s),
+                "n_missing_in_frame": int(prices[col].isna().sum()),
+            }
+        )
+    return pd.DataFrame(rows).set_index("asset")

portpy/core/currency.py

@@ -0,0 +1,52 @@
+"""
+Optional currency-conversion helper.
+
+By default, PortPy assumes every asset in your DataFrame is denominated in the
+same currency and never converts anything. If you *do* have a dated FX-rate
+series, use `convert_to_base_currency` before constructing a `Portfolio` to bring
+everything into one base currency.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+def convert_to_base_currency(
+    prices: pd.DataFrame,
+    fx_rates: pd.DataFrame,
+    asset_currencies: dict[str, str],
+    base_currency: str,
+) -> pd.DataFrame:
+    """
+    Convert a multi-asset price DataFrame into a single base currency.
+
+    Args:
+        prices: Columns = asset symbols, index = dates, values = prices in each
+            asset's *native* currency.
+        fx_rates: Columns = 3-letter currency codes, index = dates, values = units
+            of `base_currency` per 1 unit of that currency (a direct multiplier -
+            e.g. an "EUR" column of 1.08 means 1 EUR = 1.08 of `base_currency`).
+            Reindexed to `prices.index` and forward-filled, so it doesn't need to
+            share the exact same calendar.
+        asset_currencies: Mapping of asset symbol -> currency code. Assets already
+            in `base_currency` (or missing from this dict) are left untouched.
+        base_currency: The target currency code (e.g. "USD").
+
+    Returns:
+        A new DataFrame, same shape as `prices`, denominated in `base_currency`.
+    """
+    converted = prices.copy()
+    fx_aligned = fx_rates.reindex(prices.index).ffill()
+
+    for asset, ccy in asset_currencies.items():
+        if asset not in converted.columns or ccy == base_currency:
+            continue
+        if ccy not in fx_aligned.columns:
+            raise ValueError(
+                f"No FX rate column found for currency {ccy!r} (needed by asset {asset!r}). "
+                f"fx_rates columns: {list(fx_rates.columns)}"
+            )
+        converted[asset] = converted[asset] * fx_aligned[ccy]
+
+    return converted

portpy/core/weights.py

@@ -0,0 +1,69 @@
+"""
+Portfolio weight validation and normalization.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def equal_weights(names: list[str]) -> pd.Series:
+    """
+    Build a 1/N weight vector for the given asset names.
+    """
+    n = len(names)
+    if n == 0:
+        raise ValueError("Cannot build weights for zero assets.")
+    return pd.Series(np.full(n, 1.0 / n), index=list(names), name="weight")
+
+
+def normalize_weights(
+    weights: pd.Series | np.ndarray | dict | list,
+    names: list[str] | None = None,
+    allow_negative: bool = True,
+) -> pd.Series:
+    """
+    Validate a weights input and rescale it so it sums to 1.
+
+    Args:
+        weights: A Series/dict keyed by asset name, or a plain array/list aligned
+            with `names`.
+        names: Required asset order when `weights` isn't already labeled; also used
+            to check that every asset has a weight.
+        allow_negative: If False, raise when any weight is negative (e.g. for
+            long-only optimizers).
+
+    Returns:
+        A Series of weights summing to 1.0, indexed by `names` (in that order) when
+        `names` is given.
+    """
+    if isinstance(weights, dict):
+        weights = pd.Series(weights, dtype=float)
+    elif isinstance(weights, pd.Series):
+        weights = weights.astype(float)
+    elif isinstance(weights, (list, tuple, np.ndarray)):
+        if names is None:
+            raise ValueError("`names` is required when `weights` is a list/array.")
+        arr = np.asarray(weights, dtype=float)
+        if len(arr) != len(names):
+            raise ValueError(f"weights has {len(arr)} entries but {len(names)} names were given.")
+        weights = pd.Series(arr, index=list(names))
+    else:
+        raise TypeError(f"Unsupported weights type: {type(weights).__name__}")
+
+    if names is not None:
+        missing = set(names) - set(weights.index)
+        if missing:
+            raise ValueError(f"Weights are missing for assets: {sorted(missing)}")
+        weights = weights.reindex(list(names))
+
+    if weights.isna().any():
+        raise ValueError("Weights contain NaN values.")
+    if not allow_negative and (weights < 0).any():
+        raise ValueError("Negative weights are not allowed here (long-only constraint).")
+
+    total = weights.sum()
+    if np.isclose(total, 0.0):
+        raise ValueError("Weights sum to zero; cannot normalize.")
+    return (weights / total).rename("weight")

portpy/explain.py

@@ -0,0 +1,235 @@
+"""
+PortPy's built-in explainability layer.
+
+This is what turns PortPy from a "numbers and charts out" library into a teaching
+tool: every metric, chart, model, and strategy can tell you, in plain language,
+what it is, how to read it, and whether the number you got is good or bad.
+
+Three pieces work together:
+
+- :class:`Explanation` - a structured knowledge card (what it is / how to read it /
+  good vs. bad / caveats / formula), optionally with a function that turns a
+  concrete computed value into a one-line verdict.
+- A module-level registry mapping names ("sharpe_ratio", "drawdown_chart",
+  "capm", "buy_and_hold", ...) to their :class:`Explanation`.
+- :class:`MetricResult` - a float subclass returned by metric functions when
+  as_result=True. It behaves exactly like a float everywhere (math, comparisons,
+  formatting, numpy/pandas operations) but also carries a .explain() method and
+  a .interpretation property.
+
+The same registry backs charts (fig.explain() in :mod:`portpy.visualization`),
+models, and strategies (.describe() / .diagnose() in :mod:`portpy.models`
+and :mod:`portpy.strategies`), so portpy.explain(x) works uniformly on any of
+them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "Explanation",
+    "MetricResult",
+    "register",
+    "get",
+    "explain",
+    "available",
+]
+
+_CATEGORIES = ("metric", "chart", "model", "strategy", "function")
+
+
+@dataclass(frozen=True)
+class Explanation:
+    """
+    A structured, human-readable knowledge card attached to a PortPy object.
+
+    Attributes:
+        name: Registry key, matching the function/chart/model/strategy name
+            (e.g. "sharpe_ratio", "drawdown_chart", "capm").
+        category: One of "metric", "chart", "model", "strategy".
+        summary: One or two sentences on what this *is*.
+        how_to_read: How to read the number/axis/output in practice.
+        good_vs_bad: Rules of thumb for judging whether a value is good or bad.
+        caveats: Known limitations, edge cases, or ways this can mislead.
+        formula: Optional plain-text formula for reference.
+        interpret: Optional function mapping a concrete value to a one-line verdict,
+            used to render a "this result" line when a value is available.
+    """
+
+    name: str
+    category: str
+    summary: str
+    how_to_read: str
+    good_vs_bad: str
+    caveats: str = ""
+    formula: str = ""
+    interpret: Callable[[Any], str] | None = field(default=None, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.category not in _CATEGORIES:
+            raise ValueError(f"category must be one of {_CATEGORIES}, got {self.category!r}")
+
+    def render(self, value: Any = None) -> str:
+        """
+        Render this card as plain text, optionally with a value-specific verdict.
+        """
+        lines = [f"{self.name} ({self.category})", "=" * len(f"{self.name} ({self.category})")]
+        lines += ["", "What it is:", f"  {self.summary}"]
+        if self.formula:
+            lines += ["", "Formula:", f"  {self.formula}"]
+        lines += ["", "How to read it:", f"  {self.how_to_read}"]
+        lines += ["", "Good vs. bad:", f"  {self.good_vs_bad}"]
+        if self.caveats:
+            lines += ["", "Caveats:", f"  {self.caveats}"]
+        if value is not None and self.interpret is not None:
+            try:
+                lines += ["", "This result:", f"  {self.interpret(value)}"]
+            except Exception:
+                pass
+        return "\n".join(lines)
+
+
+_REGISTRY: dict[str, Explanation] = {}
+
+
+def register(explanation: Explanation) -> Explanation:
+    """
+    Register (or overwrite) an :class:`Explanation` in the global registry.
+    """
+    _REGISTRY[explanation.name] = explanation
+    return explanation
+
+
+def get(name: str) -> Explanation:
+    """
+    Look up a registered :class:`Explanation` by name.
+    """
+    try:
+        return _REGISTRY[name]
+    except KeyError as exc:
+        raise KeyError(
+            f"No explanation registered for {name!r}. "
+            f"Call portpy.explain.available() to list all {len(_REGISTRY)} registered names."
+        ) from exc
+
+
+def available(category: str | None = None) -> list[str]:
+    """
+    List registered explanation names, optionally filtered by category."""
+    if category is None:
+        return sorted(_REGISTRY)
+    return sorted(k for k, v in _REGISTRY.items() if v.category == category)
+
+
+def explain(obj: Any, *, value: Any = None, print_it: bool = True) -> str:
+    """
+    Explain a metric name, :class:`MetricResult`, chart, model, or strategy.
+
+    Args:
+        obj: A registered name (str), a :class:`MetricResult`, or any PortPy
+            object that exposes a _portpy_explain_name attribute (charts, fitted
+            models, strategies) or a pandas .attrs["portpy_explanation"] entry.
+        value: Optional concrete value to generate a one-line verdict for. Inferred
+            automatically for :class:`MetricResult` and objects carrying
+            _portpy_explain_value.
+        print_it: If True (default), also print() the rendered text.
+
+    Returns:
+        The rendered explanation text.
+    """
+    name: str | None = None
+
+    if isinstance(obj, str):
+        name = obj
+    elif isinstance(obj, MetricResult):
+        name = obj.name
+        if value is None:
+            value = float(obj)
+    elif hasattr(obj, "_portpy_explain_name"):
+        name = obj._portpy_explain_name
+        if value is None:
+            value = getattr(obj, "_portpy_explain_value", None)
+    else:
+        attrs = getattr(obj, "attrs", None)
+        if isinstance(attrs, dict) and "portpy_explanation" in attrs:
+            name = attrs["portpy_explanation"]
+
+    if name is None:
+        raise TypeError(
+            f"Don't know how to explain an object of type {type(obj).__name__!r}. "
+            "Pass a registered name (str), a MetricResult, or a PortPy chart/model/strategy."
+        )
+
+    text = get(name).render(value)
+    if print_it:
+        print(text)
+    return text
+
+
+class MetricResult(float):
+    """
+    A float that also knows what it means.
+
+    Arithmetic, comparisons, round(), string formatting, and numpy/pandas
+    interop all work exactly as they would on a plain float (this *is* a float
+    subclass). On top of that, it carries the metric's registered name and can
+    render a full explanation on demand.
+
+    Note:
+        str(result) prints the plain number (so print(sharpe) stays clean);
+        repr(result) - what you see when a bare expression is evaluated in a
+        REPL/notebook - includes the name and a one-line interpretation.
+    """
+
+    name: str
+    unit: str | None
+    meta: dict
+
+    def __new__(
+        cls,
+        value: float,
+        name: str,
+        unit: str | None = None,
+        meta: dict | None = None,
+    ) -> MetricResult:
+        obj = super().__new__(cls, value)
+        obj.name = name
+        obj.unit = unit
+        obj.meta = meta or {}
+        return obj
+
+    @property
+    def value(self) -> float:
+        return float(self)
+
+    @property
+    def interpretation(self) -> str:
+        """
+        A one-line, value-specific verdict (empty string if none is registered).
+        """
+        expl = _REGISTRY.get(self.name)
+        if expl is None or expl.interpret is None:
+            return ""
+        try:
+            return expl.interpret(float(self))
+        except Exception:
+            return ""
+
+    def explain(self, print_it: bool = True) -> str:
+        """
+        Print (by default) and return the full explanation for this result.
+        """
+        return explain(self, print_it=print_it)
+
+    def __str__(self) -> str:
+        return str(float(self))
+
+    def __repr__(self) -> str:
+        base = f"{float(self):.6g}"
+        unit_str = f" {self.unit}" if self.unit else ""
+        interp = self.interpretation
+        suffix = f" - {interp}" if interp else ""
+        return f"{self.name}={base}{unit_str}{suffix}"

portpy/metrics/__init__.py

@@ -0,0 +1,57 @@
+"""
+Pure, stateless metric functions, grouped by topic.
+
+Every public function here also works standalone (pass a plain pandas Series/
+DataFrame) - :class:`~portpy.portfolio.Portfolio` methods are thin wrappers
+around these.
+"""
+
+from portpy.metrics import (
+    benchmarks,
+    costs,
+    covariance,
+    distributions,
+    drawdowns,
+    performance,
+    regressions,
+    returns,
+    risk,
+    rolling,
+    summary,
+)
+from portpy.metrics.benchmarks import *  # noqa: F401,F403
+from portpy.metrics.costs import *  # noqa: F401,F403
+from portpy.metrics.covariance import *  # noqa: F401,F403
+from portpy.metrics.distributions import *  # noqa: F401,F403
+from portpy.metrics.drawdowns import *  # noqa: F401,F403
+from portpy.metrics.performance import *  # noqa: F401,F403
+from portpy.metrics.regressions import *  # noqa: F401,F403
+from portpy.metrics.returns import *  # noqa: F401,F403
+from portpy.metrics.risk import *  # noqa: F401,F403
+from portpy.metrics.rolling import *  # noqa: F401,F403
+from portpy.metrics.summary import *  # noqa: F401,F403
+
+__all__ = [
+    "benchmarks",
+    "costs",
+    "covariance",
+    "distributions",
+    "drawdowns",
+    "performance",
+    "regressions",
+    "returns",
+    "risk",
+    "rolling",
+    "summary",
+    *benchmarks.__all__,
+    *costs.__all__,
+    *covariance.__all__,
+    *distributions.__all__,
+    *drawdowns.__all__,
+    *performance.__all__,
+    *regressions.__all__,
+    *returns.__all__,
+    *risk.__all__,
+    *rolling.__all__,
+    *summary.__all__,
+]