openfactsheet 0.1.0a1__py3-none-any.whl

openfactsheet/__init__.py

@@ -0,0 +1,47 @@
+"""OpenFactsheet — standardized, transparent investment performance analytics
+without metric cherry-picking.
+
+>>> import openfactsheet as ofs
+>>> report = ofs.analyze(returns)                      # doctest: +SKIP
+>>> print(report.summary())                            # doctest: +SKIP
+"""
+
+from openfactsheet.api import analyze, compare, load, methodology, metric_catalog
+from openfactsheet.exceptions import (
+    AmbiguousReturnScaleError,
+    BenchmarkAlignmentError,
+    FactorAlignmentError,
+    FrequencyInferenceError,
+    InputError,
+    MetricCalculationError,
+    OCRExtractionError,
+    OpenFactsheetError,
+)
+from openfactsheet.models.input import ObservationFrequency, ReturnSeries, ReturnTable
+from openfactsheet.models.metric import MetricResult
+from openfactsheet.models.report import FactsheetReport
+from openfactsheet.policy.methodology_version import METHODOLOGY_VERSION
+from openfactsheet.version import __version__
+
+__all__ = [
+    "METHODOLOGY_VERSION",
+    "AmbiguousReturnScaleError",
+    "BenchmarkAlignmentError",
+    "FactorAlignmentError",
+    "FactsheetReport",
+    "FrequencyInferenceError",
+    "InputError",
+    "MetricCalculationError",
+    "MetricResult",
+    "OCRExtractionError",
+    "ObservationFrequency",
+    "OpenFactsheetError",
+    "ReturnSeries",
+    "ReturnTable",
+    "__version__",
+    "analyze",
+    "compare",
+    "load",
+    "methodology",
+    "metric_catalog",
+]

openfactsheet/api.py

@@ -0,0 +1,304 @@
+"""Public API: ``analyze``, ``compare``, ``load``, ``metric_catalog``, ``methodology``.
+
+The API is intentionally small. There are no knobs for metric windows,
+thresholds, confidence levels or metric subsets: the canonical methodology
+decides. The only optional arguments *describe the input* when it cannot be
+established from the data itself (percent vs decimal scale, frequency of
+undated values); such declarations are recorded in the report.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+from openfactsheet.exceptions import InputError
+from openfactsheet.factors.data import load_factor_set
+from openfactsheet.input.dispatcher import to_raw
+from openfactsheet.metrics.registry import all_metrics
+from openfactsheet.models.assumptions import Methodology
+from openfactsheet.models.input import (
+    InputDiagnostics,
+    ObservationFrequency,
+    RawReturns,
+    ReturnSeries,
+    ReturnTable,
+)
+from openfactsheet.models.report import FactsheetReport
+from openfactsheet.normalization.returns import normalize_returns
+from openfactsheet.normalization.scaling import DeclaredScale
+from openfactsheet.policy.defaults import canonical_methodology
+from openfactsheet.policy.thresholds import get_policy
+from openfactsheet.report.builder import build_report
+
+if TYPE_CHECKING:
+    from openfactsheet.compare.comparison import Comparison
+
+
+def _normalize_one(
+    source: Any,
+    *,
+    name: str | None,
+    return_scale: DeclaredScale | None,
+    frequency: str | ObservationFrequency | None,
+    role: str,
+) -> tuple[ReturnSeries, InputDiagnostics]:
+    if isinstance(source, RawReturns) and name is not None:
+        source = replace(source, name=name)
+    if isinstance(source, ReturnSeries):
+        if source.input_diagnostics is not None and return_scale is None and frequency is None:
+            if name is not None and name != source.name:
+                diag = replace(source.input_diagnostics, name=name)
+                return replace(source, name=name, input_diagnostics=diag), diag
+            return source, source.input_diagnostics
+        source = RawReturns(
+            values=source.values,
+            dates=source.dates,
+            name=name or source.name,
+            source_type=source.source_type,
+        )
+        return_scale = return_scale or "decimal"
+    raws = to_raw(source, name=name)
+    if role == "returns":
+        raws = _select_document_fund(raws) or raws
+    if len(raws) != 1:
+        names = ", ".join(r.name for r in raws)
+        raise InputError(
+            f"The {role} input contains {len(raws)} return series ({names}); analyze() expects "
+            "exactly one. Select a column, or use ofs.compare() for several series."
+        )
+    return normalize_returns(raws[0], return_scale=return_scale, frequency=frequency)
+
+
+def _role(raw: RawReturns) -> str | None:
+    extraction = raw.metadata.get("extraction")
+    return extraction.get("role") if isinstance(extraction, Mapping) else None
+
+
+def _select_document_fund(raws: list[RawReturns]) -> list[RawReturns] | None:
+    """For documents with fund and benchmark tables, the single fund series (decision 0033).
+
+    Benchmark returns found in a document are never used as benchmark returns; the
+    fund series records that they exist. Returns ``None`` when no document roles
+    apply (the caller then applies the usual one-series rule).
+    """
+    roles = [_role(r) for r in raws]
+    if not any(roles):
+        return None
+    funds = [r for r, role in zip(raws, roles, strict=True) if role != "benchmark"]
+    benchmarks = [r.name for r, role in zip(raws, roles, strict=True) if role == "benchmark"]
+    if not funds:
+        raise InputError(
+            "The document's only return table is labelled as benchmark returns ("
+            + ", ".join(benchmarks)
+            + "); it is not analyzed as the fund. Load it with ofs.load() to use it explicitly."
+        )
+    if len(funds) != 1:
+        return funds
+    if not benchmarks:
+        return funds
+    note = (
+        "The document also shows benchmark returns ("
+        + ", ".join(benchmarks)
+        + "); they were not used. Pass them with benchmark=... (e.g. from ofs.load()) to "
+        "compute benchmark-relative metrics."
+    )
+    return [replace(funds[0], warnings=(*funds[0].warnings, note))]
+
+
+def normalize_benchmark(
+    benchmark: Any,
+    *,
+    return_scale: DeclaredScale | None = None,
+    frequency: str | ObservationFrequency | None = None,
+) -> tuple[ReturnSeries, InputDiagnostics]:
+    """Normalize benchmark input as :func:`analyze` does (named ``Benchmark`` by default)."""
+    bench_name = (
+        str(benchmark.name)
+        if isinstance(benchmark, pd.Series) and benchmark.name is not None
+        else None
+    )
+    return _normalize_one(
+        benchmark,
+        name=bench_name or (None if isinstance(benchmark, ReturnSeries) else "Benchmark"),
+        return_scale=return_scale,
+        frequency=frequency,
+        role="benchmark",
+    )
+
+
+def load(
+    source: Any,
+    *,
+    name: str | None = None,
+    return_scale: DeclaredScale | None = None,
+    frequency: str | ObservationFrequency | None = None,
+    ocr_engine: str | None = None,
+) -> ReturnSeries | ReturnTable:
+    """Parse and normalize input without computing metrics.
+
+    Inspect ``series.input_diagnostics`` to see exactly what OpenFactsheet
+    believes it received before analyzing it.
+
+    Args:
+        source: Returns in any form :func:`analyze` accepts, including CSV, Excel,
+            pasted monthly tables, PDF factsheets and screenshots.
+        name: Display name for a single series.
+        return_scale: Declare ``"decimal"`` or ``"percent"`` only when automatic
+            detection reports ambiguity.
+        frequency: Declare the observation frequency of *undated* values.
+        ocr_engine: ``"rapidocr"`` (default) or ``"tesseract"`` for images and
+            scanned PDF pages. It never changes an accepted value, because
+            recognized tables must reconcile with their printed totals.
+
+    Returns:
+        A :class:`ReturnSeries` for a single series, or a :class:`ReturnTable`
+        when the source contains several return columns (for example a fund and
+        the benchmark printed in a factsheet).
+
+    Examples:
+        >>> series = ofs.load("monthly_returns.csv")
+        >>> print(series.input_diagnostics.to_text())
+    """
+    raws = to_raw(source, name=name, ocr_engine=ocr_engine)
+    normalized = [
+        normalize_returns(r, return_scale=return_scale, frequency=frequency)[0] for r in raws
+    ]
+    if len(normalized) == 1:
+        return normalized[0]
+    return ReturnTable({s.name: s for s in normalized})
+
+
+def analyze(
+    returns: Any,
+    benchmark: Any = None,
+    *,
+    factors: Any = None,
+    name: str | None = None,
+    return_scale: DeclaredScale | None = None,
+    frequency: str | ObservationFrequency | None = None,
+) -> FactsheetReport:
+    """Produce the canonical OpenFactsheet report for one return history.
+
+    Args:
+        returns: A list/tuple/array of returns, a pandas Series (ideally with a
+            DatetimeIndex), a one-column DataFrame, a CSV/Excel path, pasted table
+            text, or a :class:`ReturnSeries` from :func:`load`.
+        benchmark: Optional benchmark returns in any of the same forms. Benchmark-
+            relative metrics are computed only when a benchmark is supplied.
+        factors: Optional factor returns, one column per factor (a DataFrame, a
+            CSV/Excel path or table text, e.g. Fama-French factors). A column named
+            ``RF`` is the risk-free rate and is subtracted from fund returns. Factor-
+            model metrics are computed only when factors are supplied; OpenFactsheet
+            never downloads factor data.
+        name: Display name for the report.
+        return_scale: Declare ``"decimal"`` or ``"percent"`` only when automatic
+            detection reports ambiguity. Applies to fund, benchmark and factors.
+        frequency: Declare the observation frequency of *undated* values. It is
+            checked against dates when dates exist. Applies to fund, benchmark and
+            factors.
+
+    Returns:
+        A :class:`FactsheetReport` containing every canonical metric with its
+        status, confidence, warnings and assumptions.
+
+    Examples:
+        >>> report = ofs.analyze(returns)
+        >>> print(report.summary())
+        >>> report.metrics["sharpe_ratio"].value
+        >>> report = ofs.analyze(returns, benchmark=benchmark_returns)
+        >>> report.to_html("factsheet.html")
+    """
+    series, diag = _normalize_one(
+        returns, name=name, return_scale=return_scale, frequency=frequency, role="returns"
+    )
+    bench_series = bench_diag = None
+    if benchmark is not None:
+        bench_series, bench_diag = normalize_benchmark(
+            benchmark, return_scale=return_scale, frequency=frequency
+        )
+    factor_set = (
+        load_factor_set(factors, return_scale=return_scale, frequency=frequency)
+        if factors is not None
+        else None
+    )
+    return build_report(series, diag, bench_series, bench_diag, factor_set)
+
+
+def compare(
+    funds: Mapping[str, Any] | pd.DataFrame | Sequence[Any] | ReturnTable,
+    benchmark: Any = None,
+    *,
+    factors: Any = None,
+    return_scale: DeclaredScale | None = None,
+    frequency: str | ObservationFrequency | None = None,
+) -> Comparison:
+    """Analyze several return histories under one identical methodology.
+
+    Metrics are shown side by side; nothing is ranked. When the histories cover
+    different periods, an additional common-period analysis (the intersection of
+    all histories) is provided so that track-record differences are visible. The
+    same benchmark and factor returns, if supplied, are used for every investment.
+
+    Args:
+        funds: A mapping of name to returns, a DataFrame with one column per
+            investment, a sequence of return series, or a :class:`ReturnTable`.
+        benchmark: Optional benchmark returns, used for every investment.
+        factors: Optional factor returns, used for every investment.
+        return_scale: Declare ``"decimal"`` or ``"percent"`` only when automatic
+            detection reports ambiguity.
+        frequency: Declare the observation frequency of *undated* values.
+
+    Returns:
+        A :class:`Comparison` holding the full report of every investment.
+
+    Examples:
+        >>> comparison = ofs.compare({"Fund A": fund_a, "Fund B": fund_b, "ETF": etf})
+        >>> print(comparison.summary())
+        >>> comparison.table(common_period=True)
+    """
+    from openfactsheet.compare.comparison import build_comparison
+
+    return build_comparison(
+        funds,
+        benchmark=benchmark,
+        factors=factors,
+        return_scale=return_scale,
+        frequency=frequency,
+    )
+
+
+def metric_catalog() -> pd.DataFrame:
+    """Every canonical metric with its definition, conventions and data requirements.
+
+    Returns:
+        A DataFrame indexed by metric id, one row per canonical metric.
+
+    Examples:
+        >>> catalog = ofs.metric_catalog()
+        >>> catalog.loc["sharpe_ratio", "formula"]
+    """
+    rows = []
+    for d in all_metrics():
+        row = d.to_dict()
+        row["minimum_data"] = get_policy(d.min_data_policy).description
+        row["references"] = "; ".join(r.citation for r in d.docs.references)
+        rows.append(row)
+    return pd.DataFrame(rows).set_index("id")
+
+
+def methodology() -> Methodology:
+    """The canonical, versioned methodology used by every report.
+
+    Returns:
+        The methodology object; ``.version`` is its version and ``.to_json()``
+        the complete set of canonical conventions embedded in every report.
+
+    Examples:
+        >>> ofs.methodology().get("tail.var_confidence")
+        0.95
+    """
+    return canonical_methodology()

openfactsheet/compare/__init__.py

@@ -0,0 +1 @@
+"""Benchmark alignment and multi-investment comparison."""

openfactsheet/compare/alignment.py

@@ -0,0 +1,240 @@
+"""Fund/benchmark alignment (decision 0012). Missing returns are never filled.
+
+* Both dated, same regular frequency: monthly/quarterly/yearly observations are
+  matched by calendar period (so month-start and month-end conventions align);
+  daily/weekly by exact date. Only the intersection is used and the loss of
+  observations is disclosed.
+* Both dated, different frequencies: :class:`BenchmarkAlignmentError`
+  (no resampling in methodology 0.1.0).
+* Neither dated: aligned by position only when lengths match.
+* Exactly one dated: when lengths match, the undated series is assumed to share
+  the dated series' timestamps (warned); otherwise an error.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from functools import cached_property
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+
+from openfactsheet.exceptions import BenchmarkAlignmentError, UndefinedMetric
+from openfactsheet.models.input import ObservationFrequency, ReturnSeries
+from openfactsheet.models.report import BenchmarkDiagnostics
+
+PERIOD_CODES = {
+    ObservationFrequency.MONTHLY: "M",
+    ObservationFrequency.QUARTERLY: "Q",
+    ObservationFrequency.YEARLY: "Y",
+}
+
+
+@dataclass(frozen=True)
+class OLSResult:
+    """CAPM-style regression ``fund = alpha + beta * benchmark + e`` (statsmodels OLS)."""
+
+    alpha: float
+    beta: float
+    alpha_se: float | None
+    beta_se: float | None
+    alpha_t: float | None
+    beta_t: float | None
+    alpha_pvalue: float | None
+    beta_pvalue: float | None
+    r_squared: float
+    residual_std: float | None
+    n: int
+
+
+def _finite_or_none(x: float) -> float | None:
+    return float(x) if math.isfinite(float(x)) else None
+
+
+def single_index_ols(
+    fund: npt.NDArray[np.float64], bench: npt.NDArray[np.float64], what: str = "aligned periods"
+) -> OLSResult:
+    """OLS of ``fund`` on a constant and ``bench`` (statsmodels), with i.i.d. standard errors.
+
+    Raises :class:`UndefinedMetric` with fewer than 3 observations or a constant
+    regressor; ``what`` names the sample in those reasons.
+    """
+    n = int(fund.shape[0])
+    if n < 3:
+        raise UndefinedMetric(
+            f"At least 3 observations are required for regression; the {what} contain {n}."
+        )
+    if float(np.ptp(bench)) == 0.0:
+        raise UndefinedMetric(f"Benchmark returns are constant over the {what}; beta is undefined.")
+    if float(np.ptp(fund)) == 0.0:
+        # Exact solution: a constant fund has slope 0, intercept equal to its return and
+        # zero residuals. Solving numerically would leave rounding noise (e.g. beta = 1e-17)
+        # that downstream ratios (Treynor, appraisal) would divide by. t-statistics are 0/0.
+        return OLSResult(
+            alpha=float(fund[0]),
+            beta=0.0,
+            alpha_se=0.0,
+            beta_se=0.0,
+            alpha_t=None,
+            beta_t=None,
+            alpha_pvalue=None,
+            beta_pvalue=None,
+            r_squared=math.nan,  # undefined (no variance to explain); guarded by r_squared
+            residual_std=0.0,
+            n=n,
+        )
+    import statsmodels.api as sm
+
+    x = sm.add_constant(bench, has_constant="add")
+    fit = sm.OLS(fund, x).fit()
+    params = np.asarray(fit.params, dtype=np.float64)
+    dof = n - 2
+    bse = np.asarray(fit.bse, dtype=np.float64)
+    tvals = np.asarray(fit.tvalues, dtype=np.float64)
+    pvals = np.asarray(fit.pvalues, dtype=np.float64)
+    resid_std = math.sqrt(float(fit.ssr) / dof)
+    return OLSResult(
+        alpha=float(params[0]),
+        beta=float(params[1]),
+        alpha_se=_finite_or_none(bse[0]),
+        beta_se=_finite_or_none(bse[1]),
+        alpha_t=_finite_or_none(tvals[0]),
+        beta_t=_finite_or_none(tvals[1]),
+        alpha_pvalue=_finite_or_none(pvals[0]),
+        beta_pvalue=_finite_or_none(pvals[1]),
+        r_squared=float(fit.rsquared),
+        residual_std=_finite_or_none(resid_std),
+        n=n,
+    )
+
+
+@dataclass(frozen=True, eq=False)
+class AlignedBenchmark:
+    fund: npt.NDArray[np.float64]
+    bench: npt.NDArray[np.float64]
+    dates: pd.DatetimeIndex | None
+    diagnostics: BenchmarkDiagnostics
+    periods_per_year: float | None
+
+    @property
+    def n(self) -> int:
+        return int(self.fund.shape[0])
+
+    @cached_property
+    def active(self) -> npt.NDArray[np.float64]:
+        return self.fund - self.bench
+
+    @cached_property
+    def ols(self) -> OLSResult:
+        return single_index_ols(self.fund, self.bench)
+
+    @cached_property
+    def bull_ols(self) -> OLSResult:
+        """Single-index regression on the periods with a strictly positive benchmark return."""
+        up = self.bench > 0.0
+        return single_index_ols(self.fund[up], self.bench[up], "benchmark up periods")
+
+    @cached_property
+    def bear_ols(self) -> OLSResult:
+        """Single-index regression on the periods with a strictly negative benchmark return."""
+        down = self.bench < 0.0
+        return single_index_ols(self.fund[down], self.bench[down], "benchmark down periods")
+
+
+def period_keys(series: ReturnSeries, code: str | None) -> pd.Index:
+    assert series.dates is not None
+    if code is not None:
+        return pd.Index(series.dates.to_period(code))
+    return pd.Index(series.dates.normalize())
+
+
+def _fmt(ts: pd.Timestamp) -> str:
+    return ts.strftime("%Y-%m-%d")
+
+
+def align_benchmark(fund: ReturnSeries, bench: ReturnSeries) -> AlignedBenchmark:
+    warnings: list[str] = []
+    fr, br = fund.values, bench.values
+
+    if fund.dates is not None and bench.dates is not None:
+        f_freq, b_freq = fund.frequency, bench.frequency
+        if f_freq.is_regular and b_freq.is_regular and f_freq != b_freq:
+            raise BenchmarkAlignmentError(
+                f"Fund is {f_freq.value} but benchmark is {b_freq.value}. OpenFactsheet does not "
+                "resample returns in methodology 0.1.0; supply a benchmark at the fund's frequency."
+            )
+        # One key type for both series: the calendar period of whichever series has a
+        # period-based frequency (the other may be irregular because of gaps).
+        period_freq = f_freq if f_freq in PERIOD_CODES else b_freq
+        code = PERIOD_CODES.get(period_freq)
+        fk, bk = period_keys(fund, code), period_keys(bench, code)
+        if fk.has_duplicates or bk.has_duplicates:
+            raise BenchmarkAlignmentError(
+                "Several observations fall in the same calendar period; they cannot be aligned "
+                "by period without choosing between them."
+            )
+        common = fk.intersection(bk)
+        f_pos = fk.get_indexer(common)
+        b_pos = bk.get_indexer(common)
+        order = np.argsort(f_pos)
+        f_pos, b_pos = f_pos[order], b_pos[order]
+        dates = pd.DatetimeIndex(fund.dates[f_pos])
+        method = f"calendar {period_freq.value} period" if code is not None else "exact date"
+        aligned_f, aligned_b = fr[f_pos], br[b_pos]
+    elif fund.dates is None and bench.dates is None:
+        if fund.n != bench.n:
+            raise BenchmarkAlignmentError(
+                f"Undated fund ({fund.n} observations) and benchmark ({bench.n}) have different "
+                "lengths; supply dates so they can be aligned explicitly."
+            )
+        dates = None
+        method = "by position (both series undated)"
+        aligned_f, aligned_b = fr, br
+        warnings.append(
+            "Neither series has dates; observations were paired by position. Verify that both "
+            "cover exactly the same periods."
+        )
+    else:
+        if fund.n != bench.n:
+            raise BenchmarkAlignmentError(
+                "Only one of fund and benchmark has dates and their lengths differ; supply dates "
+                "for both."
+            )
+        dates = fund.dates if fund.dates is not None else bench.dates
+        undated = "benchmark" if bench.dates is None else "fund"
+        method = f"by position ({undated} undated; assumed to share the other series' dates)"
+        aligned_f, aligned_b = fr, br
+        warnings.append(
+            f"The {undated} series has no dates; it was assumed to cover the same periods."
+        )
+
+    n_aligned = int(aligned_f.shape[0])
+    if n_aligned < fund.n:
+        warnings.append(
+            f"{fund.n - n_aligned} fund observation(s) have no matching benchmark return and are "
+            "excluded from benchmark-relative metrics (never filled)."
+        )
+    if n_aligned == 0:
+        warnings.append("Fund and benchmark have no periods in common.")
+
+    diag = BenchmarkDiagnostics(
+        name=bench.name,
+        fund_observations=fund.n,
+        benchmark_observations=bench.n,
+        aligned_observations=n_aligned,
+        fund_only_periods=fund.n - n_aligned,
+        benchmark_only_periods=bench.n - n_aligned,
+        overlap_start=_fmt(dates[0]) if dates is not None and n_aligned else None,
+        overlap_end=_fmt(dates[-1]) if dates is not None and n_aligned else None,
+        alignment_method=method,
+        warnings=tuple(warnings),
+    )
+    return AlignedBenchmark(
+        fund=np.array(aligned_f, dtype=np.float64),
+        bench=np.array(aligned_b, dtype=np.float64),
+        dates=dates,
+        diagnostics=diag,
+        periods_per_year=fund.periods_per_year,
+    )