Skip to content

MullionGroup/epp-example-external-usage

BranchesTags

Repository files navigation

EPP Screening Model - External Usage Example

This example project demonstrates how to use the EPP Screening Model package as an external dependency in your own Python projects.

Overview

This example shows how an external team or scientist can:

  • Install the EPP Screening Model package from GitHub
  • Use the goal seek API with custom ACCU volumes
  • Run batch sensitivity analyses
  • Execute full model calculations programmatically
  • NEW: Run interactive dashboard for goal seeking and visualization

Prerequisites

  • Python 3.12+
  • UV package manager (recommended) or pip
  • GitHub authentication (one of):
    • GitHub Personal Access Token (PAT)
    • SSH keys configured with GitHub
    • GitHub CLI (gh) authenticated

Installation

Option 1: Using GitHub Personal Access Token (Most Common)

  1. Create a GitHub Personal Access Token:

    • Go to: https://github.com/settings/tokens
    • Click "Generate new token (classic)"
    • Select scopes: repo (full control of private repositories)
    • Copy the token (you'll only see it once!)

  2. Set up authentication:

    # Copy the example environment file
cp .env.example .env

# Edit .env and add your GitHub token
# GITHUB_TOKEN=ghp_your_token_here

  3. Install the EPP package:

    # Using UV (recommended) - specify v1.1.1 or later
uv add "git+https://${GITHUB_TOKEN}@github.com/MullionGroup/epp_screening_model_v3.git@v1.1.1"

# Or using pip
pip install "git+https://${GITHUB_TOKEN}@github.com/MullionGroup/epp_screening_model_v3.git@v1.1.1"

    Important: Version 1.1.1 or later is required for the Jupyter helper functions.

Option 2: Using SSH Keys (For Developers)

If you have SSH keys configured with GitHub:

# Using UV - specify v1.1.1 or later
uv add "git+ssh://git@github.com/MullionGroup/epp_screening_model_v3.git@v1.1.1"

# Or using pip
pip install "git+ssh://git@github.com/MullionGroup/epp_screening_model_v3.git@v1.1.1"

Option 3: Using GitHub CLI (Easiest for macOS)

If you have GitHub CLI installed and authenticated:

# Authenticate first (uses 1Password/Keychain)
gh auth login

# Install package - specify v1.1.1 or later
uv add "git+https://github.com/MullionGroup/epp_screening_model_v3.git@v1.1.1"

Option 4: Using Pre-built Wheel (No Git Authentication Required)

If you prefer to install from a pre-built wheel file without Git authentication:

Download from GitHub Releases:

  1. Visit the releases page: https://github.com/MullionGroup/epp_screening_model_v3/releases
  2. Download the .whl file from the desired release (e.g., v1.2.3)
  3. Install the downloaded wheel:
# Install from local wheel file
uv add epp_screening_model_v3-1.2.3-py3-none-any.whl

# Or specify the full path
uv add /path/to/epp_screening_model_v3-1.2.3-py3-none-any.whl

Install directly from GitHub release URL:

# Install v1.2.3 directly from GitHub
uv add https://github.com/MullionGroup/epp_screening_model_v3/releases/download/v1.2.3/epp_screening_model_v3-1.2.3-py3-none-any.whl

Benefits of wheel installation:

  • ✅ No Git authentication required
  • ✅ Faster installation (no cloning/building)
  • ✅ Explicit version control
  • ✅ Works in air-gapped environments (if wheel is downloaded)

Latest releases:

  • v1.4.0 (2025-11-28): ⭐ RECOMMENDED - Complete CSV removal, validation framework, CLI enhancements
  • v1.3.1 (2025-11-10): Critical bug fix (missing excel_mappings in v1.3.0)
  • v1.3.0 (2025-11-09): Excel Version Mapping Enhancement (use v1.4.0 instead)
  • v1.2.3 (2025-10-31): Full chart generation feature parity with notebook
  • v1.2.2 (2025-10-31): Fixed external project export generation
  • v1.2.1 (2025-10-31): Added --template option to analyze-gr-projects
  • v1.2.0 (2025-10-31): Added comparison tools CLI

See all releases: https://github.com/MullionGroup/epp_screening_model_v3/releases

Quick Start

1. Install Dependencies

# Using UV (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

2. Set Up Configuration

Copy the base configuration from the EPP package or create your own:

# Create a config directory
mkdir -p config

# You'll need a config.toml file - see examples/01_basic_goal_seek.py

3. Run Examples

Option A: Interactive Dashboard (NEW - Recommended) 🎉

# Install dashboard dependencies
uv sync --extra dashboard

# Launch the dashboard
./launch_dashboard.sh

# Or manually:
uv run streamlit run dashboard/app.py

The dashboard provides:

  • Quick Goal Seek: Run preset optimizations with one click
  • Interactive Charts: Explore results with Plotly visualizations
  • Multiple Configs: Support for v1_epp and v2_sfm versions
  • Export Results: Download results in JSON format
  • Modern UI: Clean, professional interface

See dashboard/README.md for full documentation.

Option B: Interactive Jupyter Notebook

# Install notebook dependencies
uv sync --extra notebook

# Launch Jupyter notebook (from project root or examples directory)
uv run jupyter notebook examples/EPP_Examples.ipynb

The notebooks:

  • Automatically adjust the working directory to find config files
  • Provide step-by-step explanations with interactive code cells
  • Generate professional visualizations and charts
  • Include comprehensive examples and use cases
  • Export results in multiple formats (CSV, Excel, PNG)

Option C: Python Scripts

# Example 1: Basic goal seek
uv run python examples/01_basic_goal_seek.py

# Example 2: Custom ACCU volumes
uv run python examples/02_custom_accu_volumes.py

# Example 3: Batch sensitivity analysis
uv run python examples/03_batch_analysis.py

# Example 4: Full model execution
uv run python examples/04_full_model_run.py

# Example 5: v2_sfm Excel version (v1.3.0+)
uv run python examples/05_v2_sfm_example.py

# Example 6: Programmatic goal seek (standalone, no helpers)
uv run python examples/06_programmatic_goal_seek.py

CLI Commands

The EPP Screening Model package includes several command-line tools that can be run directly with uv run:

Quick Reference

Command Description
epp-model Main CLI with subcommands for running model, goal seek, exports
analyze-gr-projects Batch analyze projects from TSV file
epp-export Generate full 9-sheet Excel export
epp-template Write config to Excel template (v1)
epp-template-v2 Write config to Excel template (version-aware)
epp-compare-quarterly Compare quarterly data between Excel and Python
epp-compare-annual Compare annual data (Summary_A sheet)

epp-model (Main CLI)

The main entry point with multiple subcommands:

# Show available commands
uv run epp-model --help

# Run the complete model calculation
uv run epp-model --config config/config.toml run

# Run goal seek with presets (recommended)
uv run epp-model --config config/config.toml goal-seek --preset debt-ratio-60
uv run epp-model --config config/config.toml goal-seek --preset levered-return-15

# List available presets
uv run epp-model goal-seek --list-presets

# Run goal seek with custom parameters
uv run epp-model --config config/config.toml goal-seek \
    --input-cell "Ass_Static!H197" \
    --target-cell "Ass_Static!H200" \
    --target-value 0.60 \
    --min 0.3 --max 0.95

# Goal seek with scenario overrides
uv run epp-model --config config/config.toml goal-seek \
    --preset levered-return-15 \
    --scenario scenarios/high_market.toml

# Export model results
uv run epp-model --config config/config.toml export --output-format json

# Batch export to multiple formats
uv run epp-model --config config/config.toml batch-export

# Display model info
uv run epp-model info

# Create a template configuration file
uv run epp-model create-config --output my_config.toml

analyze-gr-projects (Batch Project Analysis)

Analyze multiple projects from a TSV file and generate comprehensive reports:

# Full analysis (all features)
uv run analyze-gr-projects --input sample_batch_projects.tsv

# Custom output location
uv run analyze-gr-projects -i data.tsv -o results/my_analysis.zip

# Quick analysis (skip goal seek and exports)
uv run analyze-gr-projects -i data.tsv --no-goal-seek --no-exports

# Template-only mode (fastest, no calculations)
uv run analyze-gr-projects -i data.tsv --template-only

# With v2_sfm Excel version
uv run analyze-gr-projects -i data.tsv --excel-version v2_sfm

# Custom goal seek bounds
uv run analyze-gr-projects -i data.tsv \
    --gs-lower-multiplier 0.1 \
    --gs-upper-multiplier 3.0

Options:

  • -i, --input PATH - Input TSV file with project data (required)
  • -o, --output PATH - Output ZIP file path
  • -p, --prefix TEXT - Prefix for output files (default: epp_screening_results_)
  • --no-goal-seek - Skip goal seek analysis (faster)
  • --no-charts - Skip chart generation (faster)
  • --no-exports - Skip full Excel exports (faster)
  • --template-only - Only generate template exports (fastest)
  • --excel-version - Excel version: v1_epp, v2_sfm, or auto

epp-export (Excel Export)

Generate full 9-sheet Excel export from configuration:

# Default export
uv run epp-export --config config/config.toml

# Custom output path
uv run epp-export --config config/config.toml --output results/my_export.xlsx

# With scenario overrides
uv run epp-export --config config/config.toml \
    --scenario scenarios/high_market.toml \
    --output results/high_market_export.xlsx

epp-template (Write Config to Excel)

Write Python configuration data into an Excel template file:

# Basic usage
uv run epp-template \
    --config config/config.toml \
    --template "data/Environmental Plantings Projects - Screening Model.xlsx" \
    --output "results/config_in_excel.xlsx"

# With scenario overrides
uv run epp-template \
    --config config/config.toml \
    --scenario "scenarios/high_land_price.toml" \
    --template "data/Environmental Plantings Projects - Screening Model.xlsx" \
    --output "results/high_land_price_in_excel.xlsx"

epp-template-v2 (Version-Aware Template Writer)

Write configuration to Excel template with explicit version support:

# With v1_epp version
uv run epp-template-v2 \
    --config config/config.toml \
    --template "data/Environmental Plantings Projects - Screening Model.xlsx" \
    --output "results/config_in_excel.xlsx" \
    --excel-version v1_epp

# With v2_sfm version
uv run epp-template-v2 \
    --config config/config_v2_sfm.toml \
    --template "data/Screening Model - Update for SFM.xlsx" \
    --output "results/config_in_excel_v2.xlsx" \
    --excel-version v2_sfm

epp-compare-quarterly (Quarterly Data Comparison)

Compare quarterly data between original Excel and Python model output:

# Basic comparison
uv run epp-compare-quarterly \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx"

# With verbose output showing top differences
uv run epp-compare-quarterly \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx" \
    --verbose --top 20

# Filter by threshold (only show >1% differences)
uv run epp-compare-quarterly \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx" \
    --threshold 1.0

# Ignore specific rows
uv run epp-compare-quarterly \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx" \
    --ignore "Financing_Qtr,50" --ignore "Acc_Qtr,30"

epp-compare-annual (Annual Data Comparison)

Compare annual data (Summary_A sheet) between Excel and Python:

# Basic comparison
uv run epp-compare-annual \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx"

# With verbose output
uv run epp-compare-annual \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx" \
    --verbose --top 10

# Custom report path
uv run epp-compare-annual \
    --original "data/Original_Excel.xlsx" \
    --output "results/full_9_sheet_export.xlsx" \
    --report "results/my_annual_comparison.csv"

Example Scripts

Jupyter Notebooks (Recommended for Learning)

EPP_Examples.ipynb - Goal Seek & Scenarios

Interactive notebook covering goal seek and scenario analysis:

  • Basic goal seek with presets
  • Custom ACCU volumes
  • Batch sensitivity analysis
  • Visualizations and exports
  • Step-by-step explanations

EPP_Metrics_Examples.ipynb - Metrics Extraction (v1.1.1+) ⭐ NEW

Comprehensive metrics extraction and analysis:

  • 50+ metrics across 6 categories
  • Automatic extraction from all 9 sheets
  • Financial performance dashboards
  • Scenario-based metrics comparison
  • Professional reporting and exports

To use the notebooks:

# Install Jupyter dependencies
uv sync --extra notebook

# Start Jupyter (from project root or examples directory)
uv run jupyter notebook examples/

# The notebooks automatically adjust the working directory

Python Scripts

01_basic_goal_seek.py

Demonstrates basic goal seek using presets:

  • Find LVR for target debt ratio
  • Find property price for target IRR
  • Access financial metrics from results

02_custom_accu_volumes.py

Shows how to use custom ACCU volumes:

  • Pass ACCU volumes as Python lists
  • No TOML files required
  • Combine with parameter overrides

03_batch_analysis.py

Performs sensitivity analysis:

  • Compare multiple ACCU scenarios
  • Generate summary DataFrame
  • Export results to CSV

04_full_model_run.py

Demonstrates full model execution:

  • Run complete 9-sheet model (v1_epp version)
  • Access individual sheet results
  • Export to multiple formats

05_v2_sfm_example.py ⭐ NEW (v1.3.0+)

Demonstrates v2_sfm Excel version support:

  • Use alternative Excel format (Screening Financial Model)
  • Different parameter configurations (LVR 50%, WACC 11%, extended exit date)
  • Additional v2_sfm-specific parameters
  • Compare results between v1_epp and v2_sfm versions

Project Structure

epp-example-external-usage/
├── README.md                       # This file
├── pyproject.toml                  # UV project configuration
├── .env.example                    # GitHub token template
├── .gitignore                      # Git ignore rules
├── examples/
│   ├── EPP_Examples.ipynb          # Goal seek & scenarios (recommended)
│   ├── EPP_Metrics_Examples.ipynb  # Metrics extraction (v1.1.1+) ⭐ NEW
│   ├── 01_basic_goal_seek.py       # Basic goal seek with presets
│   ├── 02_custom_accu_volumes.py   # Custom ACCU volumes
│   ├── 03_batch_analysis.py        # Batch sensitivity analysis
│   ├── 04_full_model_run.py        # Full model (v1_epp)
│   └── 05_v2_sfm_example.py        # v2_sfm Excel version (v1.3.0+)
├── config/
│   ├── config.toml                 # Default v1_epp configuration
│   ├── config_v1_epp.toml          # Explicit v1_epp configuration
│   ├── config_v2_sfm.toml          # v2_sfm configuration (v1.3.0+)
│   └── config.toml.example         # Configuration template
├── data/
│   └── scenarios/                  # Custom scenario files
└── results/                        # Output directory

Configuration

The EPP Screening Model requires a config.toml file with model parameters. See the main EPP repository for configuration templates and examples.

Excel Version Support (v1.3.0+)

The model now supports two Excel formats:

  1. v1_epp (Environmental Plantings Projects) - Original format

    • Config: config/config.toml or config/config_v1_epp.toml
    • Default LVR: 96%, Exit: 2031, WACC: 9%

  2. v2_sfm (Screening Financial Model) - Alternative format

    • Config: config/config_v2_sfm.toml
    • Default LVR: 50%, Exit: 2036, WACC: 11%
    • Additional parameters: annual_net_revenue, annual_opex_per_ha

Key Configuration Sections

  • [static] - Static model parameters (property price, hectares, dates, financial assumptions)
  • [accu_pricing] - ACCU pricing mode (constant or curve)
  • [escalation_rates] - Quarterly escalation rates (CPI, labor, materials)
  • [csv_data_paths] - Paths to CSV data files (if used)
  • devx_allocations - Development expenditure allocation by quarter

API Documentation

Goal Seek with Presets

from epp_screening_model_v3.models.goal_seek import GoalSeekSolver, get_preset

# v1_epp (default)
solver = GoalSeekSolver('config/config.toml')
preset = get_preset('debt-ratio-60')

result = solver.solve(
    input_cell=preset.input_cell,
    target_cell=preset.target_cell,
    target_value=preset.target_value,
    bounds=(preset.min_value, preset.max_value)
)

print(f"Optimal LVR: {result.solution:.2%}")
print(f"Levered Return: {result.levered_return:.2%}")

Goal Seek with v2_sfm Excel Version (v1.3.0+)

from epp_screening_model_v3.models.goal_seek import GoalSeekSolver, get_preset

# Use v2_sfm configuration (Excel version auto-detected from config)
solver = GoalSeekSolver('config/config_v2_sfm.toml')
preset = get_preset('debt-ratio-60')

result = solver.solve(
    input_cell=preset.input_cell,
    target_cell=preset.target_cell,
    target_value=preset.target_value,
    bounds=(preset.min_value, preset.max_value)
)

print(f"Optimal LVR: {result.solution:.2%}")
print(f"Levered Return: {result.levered_return:.2%}")

Goal Seek with Custom ACCU Volumes (v1.1.1+)

Recommended Method - Using Jupyter helpers:

from epp_screening_model_v3.notebooks.epp_jupyter_helpers import goal_seek_with_accu_volumes

# Pass ACCU volumes as Python list - no TOML files needed!
result = goal_seek_with_accu_volumes(
    preset_name='debt-ratio-60',
    accu_volumes=[0.0, 6750.0, 24605.5, ..., 0.0, 0.0],  # 27 values
    config_path='config/config.toml'
)

print(f"Optimal LVR: {result.solution:.2%}")
print(f"Levered Return: {result.levered_return:.2%}")

Batch Sensitivity Analysis (v1.1.1+)

from epp_screening_model_v3.notebooks.epp_jupyter_helpers import batch_goal_seek_analysis

scenarios = {
    'Conservative': [0.0, 4500.0, ...],  # 27 values
    'Baseline': [0.0, 6000.0, ...],      # 27 values
    'Aggressive': [0.0, 6750.0, ...],    # 27 values
}

df = batch_goal_seek_analysis(
    preset_name='debt-ratio-60',
    accu_scenarios=scenarios,
    config_path='config/config.toml'
)

print(df[['scenario', 'lvr', 'unlevered_return', 'levered_return']])

Full Model Execution

from epp_screening_model_v3.models import ACCUModel

# v1_epp (default)
model = ACCUModel('config/config.toml')
results = model.calculate_full_model()

print(f"Unlevered IRR: {results.unlevered_irr:.2%}")
print(f"Levered IRR: {results.levered_irr:.2%}")

# Access individual sheets
returns_data = results.get_sheet_result('Returns_Prj')

Full Model with v2_sfm (v1.3.0+)

from epp_screening_model_v3.models import ACCUModel

# Explicitly use v2_sfm Excel version
model = ACCUModel('config/config_v2_sfm.toml', excel_version='v2_sfm')
results = model.calculate_full_model()

print(f"Unlevered IRR: {results.unlevered_irr:.2%}")
print(f"Levered IRR: {results.levered_irr:.2%}")

Available Presets

Debt Ratios (adjust LVR):

  • debt-ratio-50 - Target 50% debt-to-capex
  • debt-ratio-60 - Target 60% debt-to-capex
  • debt-ratio-70 - Target 70% debt-to-capex

Levered Returns (adjust Property Price):

  • levered-return-12 - Target 12% levered IRR
  • levered-return-15 - Target 15% levered IRR
  • levered-return-18 - Target 18% levered IRR
  • levered-return-20 - Target 20% levered IRR

Unlevered Returns (adjust Property Price):

  • unlevered-return-10 - Target 10% unlevered IRR
  • unlevered-return-12 - Target 12% unlevered IRR
  • unlevered-return-15 - Target 15% unlevered IRR

Troubleshooting

Authentication Issues

Problem: fatal: could not read Username for 'https://github.com'

Solution: Make sure you've set up authentication using one of the three methods above.

Module Not Found

Problem: ModuleNotFoundError: No module named 'epp_screening_model_v3'

Solution:

# Verify installation
uv pip list | grep epp-screening-model

# Reinstall if needed
uv add git+https://github.com/MullionGroup/epp_screening_model_v3.git --force-reinstall

Import Errors

Problem: Package imports not working

Solution: Make sure you're using the correct import paths:

# Correct
from epp_screening_model_v3.models import ACCUModel
from epp_screening_model_v3.models.goal_seek import GoalSeekSolver

# Incorrect
from epp_screening_model import ACCUModel  # Wrong package name

Support

For issues, questions, or feature requests:

License

This example project is for demonstration purposes. The EPP Screening Model package is subject to its own license terms.

Version Compatibility

This example project requires:

  • EPP Screening Model v1.4.0 or later ⭐ RECOMMENDED
  • Python 3.12+
  • UV 0.5.0+ (recommended) or pip

Version History:

  • v1.0.6: Package build was broken (skip this version)
  • v1.0.7: Fixed package imports
  • v1.0.8: Added scenario class exports
  • v1.0.9: Includes Jupyter helpers for convenient API
  • v1.1.0: Metrics system and advanced notebooks
  • v1.1.1: ACCU pricing config migration, parametric scenarios, Excel enhancements
  • v1.1.5-1.1.6: Added analyze-gr-projects CLI command
  • v1.1.7: Added epp-export and epp-template CLI commands
  • v1.2.0: Added comparison tools CLI (epp-compare-quarterly, epp-compare-annual)
  • v1.2.1: Added --template option to analyze-gr-projects
  • v1.2.2: Fixed external project export generation bug
  • v1.2.3: Full chart generation feature parity with notebook
  • v1.3.0: Excel Version Mapping Enhancement (skip - use v1.4.0 due to packaging bug)
  • v1.3.1: Critical bug fix (missing excel_mappings)
  • v1.4.0: CURRENT RECOMMENDED - Complete CSV removal, validation framework, CLI enhancements

Latest v1.4.0 Changes (2025-11-28):

  • ✅ Complete CSV Removal - Pure TOML configuration architecture
    • Removed all CSV file dependencies
    • Scenario system fully migrated to TOML
  • ✅ Comprehensive Validation Framework - Phase 2 validation complete
  • ✅ CLI Enhancements - All 7 CLI commands fully documented
  • ✅ Bug Fixes - Fixed csv_paths references in scenario loading
  • ✅ Test Updates - Goal seek tests updated with achievable target values

v1.3.x Features (included in v1.4.0):

  • ✅ Dual Excel Version Support - v1_epp and v2_sfm formats
  • ✅ Centralized Configuration Module (src/config/)
    • PathConfig - Single source of truth for file paths
    • ValidationConfig - Centralized validation settings
    • SheetNames - TOML ↔ Excel name mapping
    • ColumnLayout - Sheet-specific column configurations
  • ✅ Metadata Provider System - 14,900% performance improvement
  • ✅ Enhanced TOML Mappings - 4,500+ field definitions with metadata
  • ✅ Golden Baselines - 124,427 entries for regression testing
  • ✅ Production-Ready Architecture - Comprehensive error handling

Breaking Changes (v1.1.1+):

  • BREAKING: ACCU pricing migrated from CSV to config-only architecture
    • Removed accu_price_curve_quarterly.csv - now configured in config.toml
    • Two modes: constant (single price) or curve (109 quarterly prices)
    • See config/config.toml [accu_pricing] section for details

Upgrade to v1.4.0:

# Remove old wheel
rm epp_screening_model_v3-*.whl

# Download v1.4.0 from GitHub releases or copy from main project
cp /path/to/epp_screening_model_v3-1.4.0-py3-none-any.whl .

# Install and sync
uv sync

Last updated: 2025-11-28

About

Example project demonstrating how to use the EPP Screening Model package as an external dependency

Topics

python jupyter example accu financial-modeling carbon-credits

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages