shadowprice 0.1.0__tar.gz

shadowprice-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Normalise line endings so commits from Windows and Unix match.
+* text=auto eol=lf
+*.xlsx binary
+*.png binary

shadowprice-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    name: test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=shadowprice --cov-report=term-missing
+
+  oldest-dependencies:
+    # The lowest versions declared in pyproject.toml must keep working.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install with oldest supported dependencies
+        run: |
+          printf 'numpy==1.24.*\npandas==2.0.*\nopenpyxl==3.1.0\n' > oldest.txt
+          pip install -e ".[dev]" -c oldest.txt
+          python -c "import numpy, pandas; print('numpy', numpy.__version__, 'pandas', pandas.__version__)"
+      - run: pytest
+
+  installed-package:
+    # Build the wheel and test it the way users install it (not editable).
+    name: installed package (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build sdist and wheel
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+      - name: Install the wheel into a clean environment
+        run: |
+          python -m venv /tmp/clean || python -m venv clean-env
+          if [ -d /tmp/clean/bin ]; then PY=/tmp/clean/bin/python; \
+          elif [ -d /tmp/clean/Scripts ]; then PY=/tmp/clean/Scripts/python; \
+          else PY=clean-env/Scripts/python; fi
+          echo "PY=$PY" >> "$GITHUB_ENV"
+          WHEEL=$(ls dist/*.whl)
+          "$PY" -m pip install "${WHEEL}[excel]" pytest
+      - name: Check the installed copy is used
+        run: |
+          "$PY" -c "import shadowprice as sp; assert 'site-packages' in sp.__file__, sp.__file__; print(sp.__version__, sp.available_methods())"
+      - name: Run tests against the installed package
+        run: '"$PY" -m pytest -p no:cacheprovider'
+      - name: Run the worked example
+        run: |
+          mkdir -p run && cd run
+          "$PY" ../examples/water_network.py

shadowprice-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+# Publishing a GitHub Release (tag vX.Y.Z) uploads the package to PyPI.
+# "Run workflow" in the Actions tab can upload to TestPyPI for a trial.
+# Authentication uses PyPI trusted publishing: no passwords or tokens are stored.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Check that the release tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          version=$(python -c "import re; print(re.search(r'\"(.+)\"', open('src/shadowprice/_version.py').read()).group(1))")
+          if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match package version v${version}"
+            exit 1
+          fi
+      - name: Build and check
+        run: |
+          pip install build twine
+          python -m build
+          twine check --strict dist/*
+      - name: Test the built wheel
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install "$(ls dist/*.whl)[excel]" pytest
+          /tmp/clean/bin/python -m pytest -q -p no:cacheprovider
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/shadowprice
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/shadowprice
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

shadowprice-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.xlsx
+.ipynb_checkpoints/

shadowprice-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 — 2026-11-15
+
+First public release (alpha).
+
+* CI: tests on Linux, Windows and macOS with Python 3.11–3.14, a job with the oldest
+  supported dependencies, and a job that builds the wheel and tests the installed package.
+* README: install without git; note on installing into an IDE's environment.
+* Release workflow: publishing a GitHub Release uploads to PyPI via trusted publishing;
+  manual runs can upload to TestPyPI.
+
+* Project and scenario model with incremental (with/without) analysis.
+* Financial analysis: FNPV/FRR on investment (C) and on national capital (K), financial
+  sustainability, funding gap rate; loan schedules (annuity/linear, grace periods).
+* Economic analysis: fiscal corrections, tariff exclusion, conversion factors under
+  domestic or world numeraire, ENPV, EIRR, B/C, ENPV profile, distribution of net benefits
+  by stakeholder.
+* National parameters: SCF, SERF, shadow wage factor, traded-input CF, Ramsey SDR.
+* Method presets: `eu_2014`, `adb_2017`, `wb_2016`; custom presets from TOML files.
+* Risk analysis: sensitivity elasticities, critical variables, switching values, scenario
+  NPV, Monte Carlo (triangular, uniform, normal, discrete; Gaussian-copula correlation).
+* Benefit helpers: willingness to pay, consumer surplus (rule of half), time savings,
+  avoided costs, emissions, price paths.
+* Reporting: summary and flow tables, Excel export with English and Russian labels.

shadowprice-0.1.0/CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "shadowprice: economic cost-benefit analysis of investment projects in Python"
+type: software
+authors:
+  - family-names: Iskakov
+    given-names: Serik
+version: 0.1.0
+license: MIT
+repository-code: "https://github.com/iskakovs/shadowprice"
+keywords:
+  - cost-benefit analysis
+  - project appraisal
+  - shadow prices
+  - public investment

shadowprice-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to shadowprice
+
+## Development setup
+
+```bash
+git clone https://github.com/iskakovs/shadowprice
+cd shadowprice
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+## Ground rules
+
+* **Every parameter has a source.** Discount rates, conversion factors and reference
+  periods must cite the guideline, edition and section they come from.
+* **Every formula has a test** with an expected value computed by hand or taken from a
+  published worked example.
+* Keep the core dependencies to `numpy` and `pandas`.
+
+## Adding a method preset
+
+Presets live in `src/shadowprice/presets/<id>.toml`. Top-level keys must come before any
+table (`[sdr_options]`, `[reference_periods]`).
+
+```toml
+id = "kz_example"                      # file name without .toml
+title = "Short title"
+source = "Full reference: issuer, document, date, section"
+year = 2025
+numeraire = "domestic"                 # "domestic" or "world"
+financial_discount_rate = 0.05         # optional
+social_discount_rate = 0.08            # or use [sdr_options] / sdr_rule = "ramsey"
+default_cf = 1.0
+critical_threshold = 0.01
+notes = ["Anything users must know when applying the method."]
+
+[sdr_options]                          # optional alternative rates
+general = 0.08
+
+[reference_periods]                    # years, [min, max]
+water_supply_sanitation = [25, 30]
+```
+
+Add a test in `tests/test_conversion_methods.py` that loads the preset and checks its
+values, and list it in the README table.
+
+## Pull requests
+
+1. Open an issue describing the change.
+2. Add tests and documentation.
+3. Make sure `pytest` and `ruff` pass.
+4. Add a line to `CHANGELOG.md`.

shadowprice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serik Iskakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shadowprice-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: shadowprice
+Version: 0.1.0
+Summary: Economic cost-benefit analysis of investment projects: financial analysis, shadow prices, ENPV/EIRR and risk analysis following EU, ADB and World Bank methods.
+Project-URL: Homepage, https://github.com/iskakovs/shadowprice
+Project-URL: Issues, https://github.com/iskakovs/shadowprice/issues
+Author: Serik Iskakov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: EIRR,ENPV,conversion factors,cost-benefit analysis,economic analysis,infrastructure,project appraisal,public investment,shadow prices
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Description-Content-Type: text/markdown
+
+# shadowprice
+
+[![CI](https://github.com/iskakovs/shadowprice/actions/workflows/ci.yml/badge.svg)](https://github.com/iskakovs/shadowprice/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/shadowprice.svg)](https://pypi.org/project/shadowprice/)
+[![Python](https://img.shields.io/pypi/pyversions/shadowprice.svg)](https://pypi.org/project/shadowprice/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Economic cost-benefit analysis of investment projects in Python** — financial analysis,
+shadow prices and conversion factors, ENPV/EIRR/B-C and risk analysis, following the
+methods of the European Commission, the Asian Development Bank and the World Bank.
+
+> Status: alpha (v0.1.0). The API may change before 1.0.
+
+## Why
+
+Economic appraisal of public investment (roads, water, energy, municipal infrastructure,
+PPPs) is still done almost entirely in spreadsheets: discount factors, conversion factors
+and risk simulations are rebuilt by hand for every project, and results are hard to audit
+or reproduce. Open-source tools cover only fragments — a road-only CBA module, the UK
+Green Book in R, health-economics packages — but not the EU / development-bank method.
+
+`shadowprice` turns that method into tested, reusable code:
+
+* **Methods as data** – EU 2014 guide, ADB 2017 and World Bank 2016 rules ship as versioned
+  presets with their sources. Run the same project under different methods, or add your
+  own national rules as a TOML file.
+* **Full pipeline** – with/without (incremental) scenarios → financial analysis →
+  fiscal corrections → conversion to economic prices → ENPV, EIRR, B/C → risk analysis →
+  distribution of net benefits.
+* **Risk analysis without add-ins** – exact sensitivity elasticities, critical variables,
+  switching values and vectorised Monte Carlo with correlated inputs.
+* **Auditable output** – every line keeps its conversion factor, tax share and source;
+  results export to Excel with English or Russian labels.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install "shadowprice[excel]"
+```
+
+The latest development version from GitHub (requires [git](https://git-scm.com)):
+
+```bash
+pip install "shadowprice[excel] @ git+https://github.com/iskakovs/shadowprice"
+```
+
+Without git, from the source archive:
+
+```bash
+pip install "shadowprice[excel] @ https://github.com/iskakovs/shadowprice/archive/refs/heads/main.zip"
+```
+
+Python 3.11+. Core dependencies: `numpy` (≥ 1.24) and `pandas` (≥ 2.0); the `excel` extra adds
+`openpyxl`. CI runs the test suite on Linux, Windows and macOS with Python 3.11–3.14, with
+the oldest supported dependencies, and against the built wheel.
+
+> **Using an IDE (PyCharm, VS Code)?** Install into the interpreter your project uses — e.g.
+> from the IDE's terminal, where the project's virtual environment is already active.
+
+## Quick start
+
+```python
+import shadowprice as sp
+from shadowprice import benefits as bf
+
+p = sp.Project(
+    "Water network",
+    start_year=2026,
+    horizon=30,
+    currency="mln KZT",
+    sector="water_supply_sanitation",
+)
+
+# With-project scenario (market prices, constant 2026 prices)
+w = p.scenario("with")
+w.investment("Imported pipes", {2026: 1800, 2027: 1200}, cf="traded", tax_share=0.12, group="capex")
+w.investment("Civil works", {2026: 900, 2027: 700}, cf="non_traded", tax_share=0.12, group="capex")
+w.om("Operation", 215, start=2028, group="opex")
+w.revenue("Tariffs", 570, start=2028, group="demand")  # excluded from economic analysis
+w.benefit("Willingness to pay", bf.willingness_to_pay(6.0, 160), start=2028, group="demand")
+w.residual_straight_line(45)
+
+# Counterfactual (business as usual); the analysis uses with - without
+wo = p.scenario("without")
+wo.om("Emergency repairs", 290, group="opex")
+wo.revenue("Tariffs (current)", 430, group="demand")
+wo.benefit("Willingness to pay (current)", bf.willingness_to_pay(4.5, 160), group="demand")
+
+fin = p.financial(rate=0.04)  # FNPV/FRR(C), funding gap
+eco = p.economic("adb_2017", national=sp.NationalParameters(serf=1.05))
+
+print(fin.summary())
+print(eco.summary())  # ENPV, EIRR, B/C
+print(sp.sensitivity(eco))  # critical variables, switching values
+
+mc = sp.monte_carlo(
+    eco, {"capex": sp.Triangular(-0.05, 0, 0.35), "demand": sp.Normal(0, 0.15)}, n=10_000, seed=1
+)
+print(f"P(ENPV < 0) = {mc.prob_negative:.1%}")
+
+sp.report.to_excel("cba.xlsx", financial=fin, economic=eco, montecarlo=mc, lang="ru")
+```
+
+A complete worked example (financing, loans, sustainability, distribution analysis) is in
+[`examples/water_network.py`](examples/water_network.py).
+
+## Core concepts
+
+**Lines.** Every cash flow is a line with a *kind* — `investment`, `replacement`, `om`,
+`revenue`, `residual` (financial analysis) or `benefit`, `external_cost` (economic only).
+Values are positive magnitudes in market prices; the sign follows the kind.
+
+**Scenarios.** Lines live in a `"with"` scenario and, optionally, a `"without"`
+counterfactual. All indicators are computed on the increment, so avoided costs in the
+counterfactual become benefits automatically.
+
+**Economic prices.** For each line: `economic = market × (1 − tax_share) × CF`. Revenues
+(tariffs) are transfers and are dropped unless flagged `as_benefit=True`; benefits are
+entered directly at economic prices.
+
+| CF tag | Domestic numeraire (ADB, WB) | World numeraire (EU 2014) |
+|---|---|---|
+| `"default"` | method default (1.0) | method default (1.0) |
+| `"traded"` | SERF | 1.0 (border prices) |
+| `"non_traded"` | 1.0 | SCF |
+| `"labour_*"` | shadow wage factor | shadow wage factor × SCF |
+| any other tag | `NationalParameters(factors=...)` | same |
+| a number | used as is | used as is |
+
+**Methods vs national parameters.** A `Method` holds a guideline's rules (discount rates,
+numeraire, reference periods, critical-variable threshold). Country values (SCF/SERF,
+shadow wages, specific CFs) go in `NationalParameters`. Helpers estimate them:
+`sp.scf(...)`, `sp.shadow_wage_factor(...)`, `sp.ramsey_sdr(...)`.
+
+**Risk groups.** Each line has a `group` (default: its kind). Sensitivity and Monte Carlo
+vary groups as relative changes; because NPV is linear in each group, elasticities and
+switching values are exact.
+
+## Bundled methods
+
+| id | Source | Numeraire | Discount rates |
+|---|---|---|---|
+| `eu_2014` | EC DG REGIO, *Guide to CBA of Investment Projects* (2014) | world | financial 4% real; social 5% (Cohesion) / 3% (other) |
+| `adb_2017` | ADB, *Guidelines for the Economic Analysis of Projects* (2017) | domestic | 9% (EOCC) |
+| `wb_2016` | World Bank, *Discounting Costs and Benefits in Economic Analysis* (2016) | domestic | Ramsey rule: SDR = 2 × per-capita growth |
+
+`sp.method("eu_2014").reference_period("roads")` returns the recommended reference period
+`(25, 30)`. Custom or national methods load from a TOML file: `sp.method("path/to/kz.toml")`.
+
+## Conventions
+
+* The first year of the reference period is `t = 0` and is not discounted.
+* Use constant (real) prices with real discount rates; `sp.discounting.deflate` converts
+  nominal series.
+* B/C = PV of lines with positive economic PV ÷ PV of lines with negative economic PV.
+* When cash flows have several IRRs, the lowest is returned with a warning; rely on NPV.
+
+## Roadmap
+
+* **v0.2** – validation suite reproducing published worked examples (EU guide case
+  studies, ADB conversion-factor water example); Kazakh labels; live-formula Excel export;
+  estimation of national parameters (SCF/SERF, shadow wage) from trade and labour data.
+* **v0.3** – `ppp` module: public sector comparator, shadow bid, risk transfer, value for
+  money, fiscal commitments.
+* **v0.4** – `rab` module: regulatory asset base roll-forward, WACC, building blocks,
+  tariff path.
+
+## Contributing
+
+Contributions are welcome, especially new method presets and national parameters with
+documented sources. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Citation
+
+If you use `shadowprice` in research, please cite it (see [CITATION.cff](CITATION.cff)).
+
+## License
+
+MIT © 2026 Serik Iskakov