eetc-utils 1.4.0

EETC Utils Library

EETC Utils

A Python library providing reusable utilities for financial analysis and algorithmic trading. Built by East Empire Trading Company for quantitative finance and trading strategy development.

Features

Finance Utilities

• Quantitative Finance Functions: Kelly Criterion position sizing, DCF valuation, compound interest
• GARCH Models: Advanced volatility forecasting using ARCH library integration
• OHLC Data Manipulation: Convert daily data to weekly timeframes, performance calculations

Options Trading

• Black-Scholes Pricing: Calculate option prices for calls and puts
• Greeks Calculations: Gamma exposure (GEX) and other option Greeks
• Volatility Analysis: Convert option IV to underlying IV, standard distribution functions
• Strike Range Tools: Find strike prices within percentage ranges

API Clients

• EETC Data Hub Client: Fetch price data, fundamentals, macroeconomic indicators, and order history
• EETC Notifications Client: Send trade updates and notifications to Telegram channels

Strategy Framework

• Live Trading: Abstract base classes for implementing live/paper trading strategies
• Execution Engine: Production-ready engine for running trading strategies
• Backtesting Framework: Complete backtesting suite with broker simulation, performance metrics, and result persistence

Installation

pip install eetc-utils

Quick Start

Finance Utilities

from eetc_utils.finance import (
    calculate_optimal_leverage_kelly,
    intrinsic_value_using_dcf,
    garch_annualized_volatility,
    convert_daily_ohlc_data_to_weekly
)
import pandas as pd

# Calculate optimal leverage using Kelly Criterion
price_df = pd.DataFrame({
    'date': pd.date_range('2020-01-01', periods=200),
    'close': [100 + i * 0.5 for i in range(200)]
})

leverage = calculate_optimal_leverage_kelly(
    df=price_df,
    position_type="LONG",
    regime_start_date="2020-01-01",
    fractional_kelly_multiplier=0.5,
    use_garch=False
)

# DCF valuation
intrinsic_value = intrinsic_value_using_dcf(
    cash_flow=1000000000,
    growth_years=10,
    shares=100000000,
    growth_rate=1.15,
    beta=1.2
)

# Forecast volatility using GARCH
volatility = garch_annualized_volatility(price_df)

# Convert daily OHLC to weekly
weekly_df = convert_daily_ohlc_data_to_weekly(price_df)

Options Trading

from eetc_utils.options import (
    calculate_option_price_black_scholes,
    find_strikes_in_range,
    GEX,
    calculate_underlying_iv_from_option_iv
)

# Calculate Black-Scholes option price
call_price = calculate_option_price_black_scholes(
    right="C",
    und_price=100.0,
    strike=105.0,
    rate=0.05,
    tte=0.5,
    implied_vol=0.25,
    pv_dividend=0.0
)

# Find strike prices within a range
strikes = find_strikes_in_range(
    range_length_perc=0.1,
    price=100.0
)

# Calculate Gamma Exposure
gex = GEX(oi=1000, gamma=0.05)

# Convert option IV to underlying IV
underlying_iv = calculate_underlying_iv_from_option_iv(
    option_implied_vol=0.20,
    t=30/365
)

EETC Data Hub Client

from eetc_utils.clients.eetc_data import EETCDataClient
import os

# Initialize client (requires EETC_API_KEY environment variable)
client = EETCDataClient(api_key=os.getenv("EETC_API_KEY"))

# Fetch price data
price_data = client.get_price_data(symbol="AAPL", start_date="2024-01-01")

# Get fundamentals
fundamentals = client.get_fundamentals(symbol="AAPL")

# Fetch macroeconomic indicators
macro_data = client.get_macro_indicators(indicator="GDP", country="US")

EETC Notifications Manager Client

from eetc_utils.clients.eetc_notifications import EETCNotificationsClient
import os

# Initialize client (requires EETC_API_KEY environment variable)
client = EETCNotificationsClient(api_key=os.getenv("EETC_API_KEY"))

# Send trade update via Telegram
client.send_trade_update_to_telegram(msg="Shorted TSLA x100 at 1312.69.")

Backtesting Framework

from eetc_utils.strategy.backtesting.strategy import Strategy
from eetc_utils.strategy.backtesting.engine import BacktestEngine
import pandas as pd

class MyStrategy(Strategy):
    def on_start(self, context):
        self.position = 0

    def on_data(self, bar, context):
        # Simple moving average crossover
        if len(self.data) < 20:
            return

        sma_short = self.data['close'].tail(5).mean()
        sma_long = self.data['close'].tail(20).mean()

        if sma_short > sma_long and self.position == 0:
            context['place_order']('buy', quantity=100)
            self.position = 100
        elif sma_short < sma_long and self.position > 0:
            context['place_order']('sell', quantity=100)
            self.position = 0

    def on_stop(self, context):
        pass

# Load historical data
data = pd.read_csv("AAPL_historical.csv")

# Run backtest
engine = BacktestEngine(
    strategy=MyStrategy(),
    data=data,
    symbol="AAPL",
    initial_capital=100000,
    commission=0.001
)

results = engine.run()
print(f"Total Return: {results['total_return']:.2%}")
print(f"Sharpe Ratio: {results['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {results['max_drawdown']:.2%}")

Documentation

Module Structure

src/eetc_utils/
├── finance.py              # Quantitative finance utilities
├── options.py              # Options pricing and Greeks
├── clients/
│   ├── eetc_data.py       # EETC Data Hub API client
│   └── eetc_notifications.py  # Notifications client
└── strategy/
    ├── strategy.py         # Live trading strategy base class
    ├── engine.py          # Live trading execution engine
    └── backtesting/
        ├── strategy.py    # Backtesting strategy base class
        ├── engine.py      # Backtesting engine
        ├── broker_sim.py  # Broker simulator
        └── metrics.py     # Performance metrics

Key Functions & Classes

Finance Module (finance.py)

• calculate_optimal_leverage_kelly(): Calculate optimal leverage using Kelly Criterion
• calculate_position_size_kelly(): Calculate position size based on Kelly Criterion
• intrinsic_value_using_dcf(): Discounted cash flow valuation
• garch_annualized_volatility(): GARCH-based volatility forecasting
• convert_daily_ohlc_data_to_weekly(): Convert daily OHLC data to weekly timeframes
• performance_over_time(): Calculate percentage performance between dates
• compound_interest(): Calculate compound interest
• beta_to_discount_rate(): Map beta to discount rate for DCF

Options Module (options.py)

• calculate_option_price_black_scholes(): Black-Scholes option pricing for calls and puts
• find_strikes_in_range(): Find strike prices within a percentage range
• GEX(): Calculate Gamma Exposure for option contracts
• calculate_underlying_iv_from_option_iv(): Convert option IV to underlying IV
• PDF(): Standard normal probability density function
• CND(): Cumulative normal distribution
• D1(), D2(): Black-Scholes d1 and d2 calculations

API Clients

• EETCDataClient: HTTP client for fetching market data and fundamentals
  • get_price_data(): Fetch historical price data
  • get_fundamentals(): Get company fundamentals
  • get_macro_indicators(): Fetch macroeconomic indicators
  • get_order_history(): Retrieve order history
• EETCNotificationsClient: Send trading notifications via Telegram
  • send_trade_update_to_telegram(): Send trade notifications

Strategy Framework

• Live Trading: Strategy (ABC) for implementing live strategies
• Backtesting: Simplified Strategy class with on_start(), on_data(), on_stop() lifecycle
• Engines: Orchestrate strategy execution (live or backtest)
• BrokerSim: Simulate order execution with configurable slippage and commission
• Metrics: Calculate Sharpe ratio, max drawdown, and other performance statistics

Development

Prerequisites

• Python 3.12+
• Poetry (for dependency management)

Setup

# Install system dependencies
sudo apt-get install build-essential

# Install Python dependencies
make update_and_install_python_requirements

Code Formatting

make reformat_code  # Uses black for consistent code style

Testing

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_financials.py

# Run with coverage
python -m pytest tests/ --cov=src/eetc_utils

Publishing to PyPI

Prerequisites

Create a .pypirc file in the project root with your PyPI API tokens:

[distutils]
index-servers =
  pypi
  testpypi

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-YOUR_TEST_PYPI_TOKEN_HERE

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-YOUR_PRODUCTION_PYPI_TOKEN_HERE

Note: The .pypirc file is already in .gitignore and will not be committed to version control.

To generate API tokens:

• TestPyPI: https://test.pypi.org/manage/account/token/
• Production PyPI: https://pypi.org/manage/account/token/

Publishing Steps

1. Update version in pyproject.toml:

   • Increment version field in [tool.poetry] section
   • Update dependencies in [tool.poetry.dependencies] if needed

2. Build the package:

   python -m build
   

3. Test on PyPI Test:

   make publish_package_on_pypi_test
   

4. Publish to production PyPI:

   make publish_package_on_pypi
   

The Makefile commands automatically read credentials from .pypirc and configure Poetry before publishing.

Configuration

Environment Variables

• EETC_API_KEY: API key for EETC Data Hub client (required for data access)

Contributing

Contributions are welcome! Please ensure:

• Code follows the project's style guide (enforced by black)
• All tests pass before submitting PR
• New features include appropriate tests
• Documentation is updated for API changes

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• East Empire Trading Company - [e-mail]
• Stefan Delic - [e-mail]
• Milos Dovedan - [e-mail]

Links

• Homepage: https://github.com/east-empire-trading-company/eetc-utils
• PyPI: https://pypi.org/project/eetc-utils/
• Bug Tracker: https://github.com/east-empire-trading-company/eetc-utils/issues

Support

For questions, issues, or feature requests, please open an issue on GitHub.