shadowprice 0.1.0__py3-none-any.whl

shadowprice/__init__.py

@@ -0,0 +1,75 @@
+"""shadowprice: economic cost-benefit analysis of investment projects.
+
+Typical workflow::
+
+    import shadowprice as sp
+
+    p = sp.Project("Water network", start_year=2026, horizon=30, currency="KZT")
+    w = p.scenario("with")
+    w.investment("Pipes", {2026: 600, 2027: 400}, cf="traded", tax_share=0.12, group="capex")
+    w.om("Operation", 25, start=2028, group="opex")
+    w.revenue("Tariffs", 90, start=2028, group="demand")
+    w.benefit("Willingness to pay", 140, start=2028, group="demand")
+
+    fin = p.financial(rate=0.04)
+    eco = p.economic("adb_2017", national=sp.NationalParameters(serf=1.05))
+    sp.sensitivity(eco)
+"""
+
+from . import benefits, conversion, discounting, report
+from ._version import __version__
+from .conversion import NationalParameters, ramsey_sdr, scf, shadow_wage_factor
+from .discounting import irr, npv
+from .economic import EconomicResult, economic_analysis
+from .financial import FinancialResult, financial_analysis
+from .financing import Financing, Loan
+from .lines import Kind, Line
+from .methods import Method, available_methods, method
+from .project import Project, Scenario
+from .risk import (
+    Discrete,
+    MonteCarloResult,
+    Normal,
+    Triangular,
+    Uniform,
+    monte_carlo,
+    scenario_npv,
+    sensitivity,
+)
+from .timeline import Timeline
+
+__all__ = [
+    "Discrete",
+    "EconomicResult",
+    "FinancialResult",
+    "Financing",
+    "Kind",
+    "Line",
+    "Loan",
+    "Method",
+    "MonteCarloResult",
+    "NationalParameters",
+    "Normal",
+    "Project",
+    "Scenario",
+    "Timeline",
+    "Triangular",
+    "Uniform",
+    "__version__",
+    "available_methods",
+    "benefits",
+    "conversion",
+    "discounting",
+    "economic_analysis",
+    "financial_analysis",
+    "irr",
+    "method",
+    "monte_carlo",
+    "npv",
+    "ramsey_sdr",
+    "report",
+    "scenario_npv",
+    "scf",
+    "sensitivity",
+    "shadow_wage_factor",
+]

shadowprice/_basis.py

@@ -0,0 +1,62 @@
+"""Common interface between analysis results and risk analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class RiskBasis:
+    """Signed line flows of an analysis, as needed by sensitivity and Monte Carlo.
+
+    Because NPV is linear in each line's scale, the risk tools work directly on
+    the present value of each line (or group of lines).
+    """
+
+    label: str
+    names: list[str]
+    groups: list[str]
+    flows: np.ndarray  # shape (lines, years), signed, in analysis prices
+    rate: float
+    threshold: float = 0.01
+
+    @property
+    def discount(self) -> np.ndarray:
+        return (1.0 + self.rate) ** -np.arange(self.flows.shape[1], dtype=float)
+
+    @property
+    def pv_lines(self) -> np.ndarray:
+        return self.flows @ self.discount
+
+    @property
+    def npv(self) -> float:
+        return float(self.pv_lines.sum())
+
+    def keys(self, level: str = "group") -> list[str]:
+        """Distinct groups (in order of appearance) or line names."""
+        if level == "line":
+            return list(self.names)
+        if level != "group":
+            raise ValueError("level must be 'group' or 'line'")
+        out: list[str] = []
+        for g in self.groups:
+            if g not in out:
+                out.append(g)
+        return out
+
+    def key_index(self, level: str = "group") -> np.ndarray:
+        """For each line, the position of its key in :meth:`keys`."""
+        keys = self.keys(level)
+        labels = self.names if level == "line" else self.groups
+        return np.array([keys.index(k) for k in labels], dtype=int)
+
+    def by(self, level: str = "group") -> tuple[list[str], np.ndarray]:
+        """Aggregate flows by ``"group"`` or by ``"line"``; returns (keys, flows)."""
+        keys = self.keys(level)
+        if level == "line":
+            return keys, self.flows
+        idx = self.key_index(level)
+        agg = np.vstack([self.flows[idx == j].sum(axis=0) for j in range(len(keys))])
+        return keys, agg

shadowprice/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

shadowprice/benefits.py

@@ -0,0 +1,65 @@
+"""Helpers to monetise common economic benefits and externalities.
+
+Each helper returns a yearly array to pass to ``Scenario.benefit`` or
+``Scenario.external_cost``. Inputs are scalars or arrays aligned with the
+project timeline; unit values must already be in economic prices.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .timeline import Timeline
+
+
+def _arr(x) -> np.ndarray:
+    return np.asarray(x, dtype=float)
+
+
+def willingness_to_pay(quantity, wtp_per_unit) -> np.ndarray:
+    """Gross benefit ``quantity x WTP`` (e.g. m3 of water supplied x WTP per m3)."""
+    return _arr(quantity) * _arr(wtp_per_unit)
+
+
+def consumer_surplus_change(
+    price_without, price_with, quantity_without, quantity_with
+) -> np.ndarray:
+    """Change in consumer surplus (rule of half) for a price reduction.
+
+    ``0.5 x (P0 - P1) x (Q0 + Q1)``: benefits to existing users plus half the
+    benefit to generated demand.
+    """
+    return (
+        0.5
+        * (_arr(price_without) - _arr(price_with))
+        * (_arr(quantity_without) + _arr(quantity_with))
+    )
+
+
+def time_savings(hours_saved, value_of_time) -> np.ndarray:
+    """Value of travel or waiting time saved: ``hours x value per hour``."""
+    return _arr(hours_saved) * _arr(value_of_time)
+
+
+def avoided_cost(cost) -> np.ndarray:
+    """Resource costs avoided thanks to the project (e.g. coping costs, damages)."""
+    return _arr(cost)
+
+
+def emissions(tonnes, price_per_tonne) -> np.ndarray:
+    """Value of emissions: ``tonnes x shadow price``.
+
+    Use with ``benefit`` for reductions and with ``external_cost`` for increases.
+    """
+    return _arr(tonnes) * _arr(price_per_tonne)
+
+
+def price_path(
+    timeline: Timeline, value_in_base_year: float, growth: float = 0.0, base_year: int | None = None
+) -> np.ndarray:
+    """Unit value growing at a constant real rate (e.g. a shadow price of carbon or value of time).
+
+    ``value_t = value_base x (1 + growth) ** (year - base_year)``.
+    """
+    base = timeline.start_year if base_year is None else base_year
+    return value_in_base_year * (1.0 + growth) ** (timeline.years - base)

shadowprice/conversion.py

@@ -0,0 +1,168 @@
+"""National economic parameters and conversion factors.
+
+Conversion factors (CFs) turn market prices into economic (shadow/accounting)
+prices: ``economic value = market value x (1 - tax share) x CF``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from .methods import Method
+
+
+def scf(
+    imports: float,
+    exports: float,
+    import_duties: float,
+    export_duties: float = 0.0,
+    import_subsidies: float = 0.0,
+    export_subsidies: float = 0.0,
+) -> float:
+    """Standard conversion factor.
+
+    General form ``(M + X) / (M + Tm - Sm + X - Tx + Sx)`` with imports ``M`` at
+    CIF, exports ``X`` at FOB, trade taxes ``T`` and subsidies ``S``. With no
+    export taxes or subsidies it reduces to the EU guide's
+    ``SCF = (M + X) / (M + X + TM)``.
+    """
+    denom = imports + import_duties - import_subsidies + exports - export_duties + export_subsidies
+    if denom <= 0:
+        raise ValueError("denominator of the SCF must be positive")
+    return (imports + exports) / denom
+
+
+def serf_from_scf(scf_value: float) -> float:
+    """Shadow exchange rate factor implied by an SCF (``SERF = 1 / SCF``)."""
+    return 1.0 / scf_value
+
+
+def traded_input_cf(import_tax: float = 0.0, vat: float = 0.0) -> float:
+    """CF of a traded input bought at a tax-inclusive market price: ``(1 - i)(1 - VAT)``.
+
+    Use either this factor *or* ``tax_share`` on the line, not both.
+    """
+    return (1.0 - import_tax) * (1.0 - vat)
+
+
+def shadow_wage_factor(income_tax: float = 0.0, unemployment: float = 0.0) -> float:
+    """Labour CF ``SW / W = (1 - t)(1 - u)`` (EU guide, unskilled labour).
+
+    ``t`` is income taxation and ``u`` the regional unemployment rate. With
+    ``unemployment=0`` it gives the shortcut ``SW = W (1 - t)``.
+    """
+    for v, n in ((income_tax, "income_tax"), (unemployment, "unemployment")):
+        if not 0.0 <= v < 1.0:
+            raise ValueError(f"{n} must be in [0, 1)")
+    return (1.0 - income_tax) * (1.0 - unemployment)
+
+
+def ramsey_sdr(growth: float, elasticity: float = 2.0, pure_time_preference: float = 0.0) -> float:
+    """Social discount rate from the Ramsey formula ``SDR = delta + eta * g``.
+
+    The defaults (``eta = 2``, ``delta = 0``) reproduce the World Bank (2016)
+    mapping: 3% per-capita growth gives a 6% SDR.
+    """
+    return pure_time_preference + elasticity * growth
+
+
+@dataclass
+class NationalParameters:
+    """Country-specific shadow-price parameters.
+
+    Parameters
+    ----------
+    scf:
+        Standard conversion factor (non-traded items, world-price numeraire).
+    serf:
+        Shadow exchange rate factor (traded items, domestic-price numeraire).
+        If omitted and ``scf`` is given, ``1 / scf`` is used.
+    shadow_wage:
+        Labour CFs by tag, expressed in domestic prices, e.g.
+        ``{"labour_unskilled": 0.75, "labour_skilled": 1.0}``.
+    factors:
+        Any other CFs by tag (e.g. ``{"electricity": 0.92, "land": 0.6}``).
+    source:
+        Where the values come from (kept in reports).
+    """
+
+    scf: float | None = None
+    serf: float | None = None
+    shadow_wage: Mapping[str, float] = field(default_factory=dict)
+    factors: Mapping[str, float] = field(default_factory=dict)
+    source: str = ""
+
+    def __post_init__(self) -> None:
+        if self.serf is None and self.scf is not None:
+            self.serf = serf_from_scf(self.scf)
+        if self.scf is None and self.serf is not None:
+            self.scf = 1.0 / self.serf
+
+
+class ConversionError(KeyError):
+    """A conversion factor could not be resolved."""
+
+
+def resolve_cf(
+    tag: str | float,
+    method: Method,
+    national: NationalParameters | None,
+    overrides: Mapping[str, float] | None = None,
+) -> float:
+    """Resolve a CF tag to a number under a method's numeraire.
+
+    Resolution order: explicit number, user overrides, built-in tags
+    (``none``, ``default``, ``traded``, ``non_traded``), labour tags, custom
+    factors in :class:`NationalParameters`.
+
+    * domestic numeraire: ``traded -> SERF``, ``non_traded -> 1``
+    * world numeraire: ``traded -> 1``, ``non_traded -> SCF``; labour CFs
+      (given in domestic prices) are multiplied by the SCF.
+    """
+    if not isinstance(tag, str):
+        return float(tag)
+    if overrides and tag in overrides:
+        return float(overrides[tag])
+    nat = national or NationalParameters()
+    world = method.numeraire == "world"
+    if tag == "none":
+        return 1.0
+    if tag == "default":
+        return method.default_cf
+    if tag == "traded":
+        if not world:
+            if nat.serf is None:
+                raise ConversionError(
+                    "tag 'traded' needs a shadow exchange rate factor under the domestic "
+                    "numeraire: pass NationalParameters(serf=...) or scf=..."
+                )
+            return nat.serf
+        return 1.0
+    if tag == "non_traded":
+        if world:
+            if nat.scf is None:
+                raise ConversionError(
+                    "tag 'non_traded' needs a standard conversion factor under the world "
+                    "numeraire: pass NationalParameters(scf=...)"
+                )
+            return nat.scf
+        return 1.0
+    if tag.startswith("labour"):
+        if tag not in nat.shadow_wage:
+            raise ConversionError(
+                f"no shadow wage factor for '{tag}': pass NationalParameters("
+                f"shadow_wage={{'{tag}': ...}}) or use shadow_wage_factor()"
+            )
+        f = float(nat.shadow_wage[tag])
+        if world:
+            if nat.scf is None:
+                raise ConversionError("labour CFs under the world numeraire need an SCF")
+            f *= nat.scf
+        return f
+    if tag in nat.factors:
+        return float(nat.factors[tag])
+    raise ConversionError(
+        f"unknown conversion-factor tag '{tag}': define it in NationalParameters(factors=...) "
+        "or pass cf={tag: value}"
+    )

shadowprice/discounting.py

@@ -0,0 +1,147 @@
+"""Discounting, NPV, IRR and price-basis helpers."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+_IRR_LO = -0.99
+_IRR_HI = 10.0
+
+
+class MultipleIRRWarning(UserWarning):
+    """Raised when a cash-flow profile has more than one internal rate of return."""
+
+
+def discount_factors(rate: float, n: int) -> np.ndarray:
+    """Discount factors ``(1 + r)^-t`` for ``t = 0..n-1``."""
+    if rate <= -1:
+        raise ValueError("discount rate must be greater than -100%")
+    return (1.0 + rate) ** -np.arange(n, dtype=float)
+
+
+def npv(rate: float, flows) -> float:
+    """Net present value with the first flow at ``t = 0`` (undiscounted)."""
+    f = np.asarray(flows, dtype=float)
+    return float(f @ discount_factors(rate, f.size))
+
+
+def present_value(rate: float, flows) -> float:
+    """Alias of :func:`npv` for one-sided streams (costs or benefits)."""
+    return npv(rate, flows)
+
+
+def _bisect(fun, lo: float, hi: float, tol: float = 1e-12, maxiter: int = 200) -> float:
+    flo = fun(lo)
+    for _ in range(maxiter):
+        mid = 0.5 * (lo + hi)
+        fmid = fun(mid)
+        if fmid == 0 or (hi - lo) < tol:
+            return mid
+        if np.sign(fmid) == np.sign(flo):
+            lo, flo = mid, fmid
+        else:
+            hi = mid
+    return 0.5 * (lo + hi)
+
+
+def irr(flows, lo: float = _IRR_LO, hi: float = _IRR_HI) -> float:
+    """Internal rate of return.
+
+    Scans ``[lo, hi]`` for sign changes of the NPV and refines each by bisection.
+    Returns ``nan`` when no IRR exists in the interval. If several roots exist
+    (non-conventional flows) the lowest is returned and a
+    :class:`MultipleIRRWarning` is issued.
+    """
+    f = np.asarray(flows, dtype=float)
+    if not (np.any(f > 0) and np.any(f < 0)):
+        return float("nan")
+    t = np.arange(f.size, dtype=float)
+
+    def fun(r: float) -> float:
+        return float(f @ (1.0 + r) ** -t)
+
+    grid = np.concatenate([np.linspace(lo, 0.0, 100, endpoint=False), np.geomspace(1e-4, hi, 400)])
+    grid = np.unique(np.concatenate([grid, [0.0]]))
+    vals = np.array([fun(r) for r in grid])
+    roots = []
+    for i in range(grid.size - 1):
+        if vals[i] == 0:
+            roots.append(float(grid[i]))
+        elif np.sign(vals[i]) != np.sign(vals[i + 1]):
+            roots.append(_bisect(fun, float(grid[i]), float(grid[i + 1])))
+    if not roots:
+        return float("nan")
+    if len(roots) > 1:
+        warnings.warn(
+            f"cash flows have {len(roots)} internal rates of return "
+            f"({', '.join(f'{r:.4f}' for r in roots)}); returning the lowest. "
+            "Rely on NPV for decisions.",
+            MultipleIRRWarning,
+            stacklevel=2,
+        )
+    return roots[0]
+
+
+def irr_vectorized(flows: np.ndarray, lo: float = _IRR_LO, hi: float = _IRR_HI) -> np.ndarray:
+    """IRR for each row of a 2-D array of cash flows (bisection, all rows at once).
+
+    Rows whose NPV does not change sign between ``lo`` and ``hi`` return ``nan``.
+    Intended for Monte Carlo draws of conventional profiles.
+    """
+    f = np.atleast_2d(np.asarray(flows, dtype=float))
+    t = np.arange(f.shape[1], dtype=float)
+
+    def npv_rows(r: np.ndarray) -> np.ndarray:
+        return np.sum(f * (1.0 + r[:, None]) ** -t, axis=1)
+
+    a = np.full(f.shape[0], lo)
+    b = np.full(f.shape[0], hi)
+    fa = npv_rows(a)
+    fb = npv_rows(b)
+    ok = np.sign(fa) != np.sign(fb)
+    for _ in range(100):
+        m = 0.5 * (a + b)
+        fm = npv_rows(m)
+        left = np.sign(fm) == np.sign(fa)
+        a = np.where(left, m, a)
+        fa = np.where(left, fm, fa)
+        b = np.where(left, b, m)
+    out = 0.5 * (a + b)
+    out[~ok] = np.nan
+    return out
+
+
+def real_rate(nominal: float, inflation: float) -> float:
+    """Fisher relation: real rate from a nominal rate and inflation."""
+    return (1.0 + nominal) / (1.0 + inflation) - 1.0
+
+
+def nominal_rate(real: float, inflation: float) -> float:
+    """Fisher relation: nominal rate from a real rate and inflation."""
+    return (1.0 + real) * (1.0 + inflation) - 1.0
+
+
+def price_index(inflation, n: int, base: int = 0) -> np.ndarray:
+    """Cumulative price index equal to 1 in period ``base``.
+
+    ``inflation`` is a scalar or an array of yearly rates of length ``n``
+    (the rate of period ``t`` applies between ``t-1`` and ``t``).
+    """
+    infl = np.broadcast_to(np.asarray(inflation, dtype=float), (n,)).copy()
+    infl[0] = 0.0
+    idx = np.cumprod(1.0 + infl)
+    return idx / idx[base]
+
+
+def deflate(nominal_values, inflation, base: int = 0) -> np.ndarray:
+    """Convert nominal values to constant (real) prices of period ``base``."""
+    v = np.asarray(nominal_values, dtype=float)
+    return v / price_index(inflation, v.size, base)
+
+
+def inflate(real_values, inflation, base: int = 0) -> np.ndarray:
+    """Convert constant prices of period ``base`` to nominal values."""
+    v = np.asarray(real_values, dtype=float)
+    return v * price_index(inflation, v.size, base)