efin 1.5.0

A comprehensive financial analysis and forecasting library

efin efin is a comprehensive Python library for financial analysis, valuation, and forecasting. It integrates data retrieval from Yahoo Finance with multiple valuation methods, risk metrics, portfolio analysis, forecasting techniques, caching, visualization, and a command-line interface (CLI). This library is ideal for investors, financial analysts, and researchers looking to quickly prototype and test financial models.

Features Valuation Models Discounted Cash Flow (DCF) Valuation: Calculates the intrinsic value of a stock based on user-supplied discount rate (WACC) and growth rate, using real free cash flow (FCF) data from Yahoo Finance.

Real FCF Retrieval: Retrieves FCF from the cash flow statement (using "Free Cash Flow" if available, or computes it from operating cash flow and CAPEX).

Dividend Discount Model (DDM): Estimates a stock's value based on expected dividend growth.

Comparable Company Analysis: Compares valuation multiples (e.g., trailing P/E) of a target company against its peers.

Residual Income Model (RIM): Estimates intrinsic value by discounting forecast residual income (EPS minus cost-of-equity on book value) over a specified period.

Forecasting Unified Forecast Function: Uses a simple linear regression model to forecast future stock prices based on historical adjusted close data.

Grid Search Auto ARIMA Forecast: Implements an automatic grid search over ARIMA parameters (p, d, q) using statsmodels to select the best ARIMA model based on AIC and forecast future prices.

Risk Metrics Volatility Calculation: Computes the standard deviation of daily returns.

Sharpe Ratio: Calculates the risk-adjusted return of a stock by comparing excess returns to volatility.

Portfolio Analysis Historical Data Aggregation: Downloads and extracts adjusted close prices for one or more tickers.

Basic Portfolio Optimization: Provides a simple, equal-weighted portfolio allocation (a placeholder for more advanced methods).

Data Caching Efficient Data Retrieval: Uses caching (via requests_cache) to store and retrieve financial data, reducing API calls and speeding up repeated analyses.

Visualization Plotting Functions: Generate visualizations to compare historical data with forecasted trends.

Command-Line Interface (CLI) Interactive CLI: Run valuations and forecasts from the terminal. The CLI supports multiple forecasting methods:

Linear Forecast: Uses the unified forecast function.

Grid Search ARIMA Forecast: Uses the auto ARIMA grid search function.

Installation:

pip install efin

Dependencies:

The library requires:

Python 3.6+:

yfinance statsmodels click requests_cache matplotlib numpy pandas scikit-learn

Usage Examples

Valuation

Discounted Cash Flow (DCF) Valuation

import efin

Calculate DCF for AAPL over a 5-year period with a 10% discount rate and 5% growth rate.

dcf_result = efin.dcf("AAPL", years=5, discount_rate=0.10, growth_rate=0.05, terminal_growth_rate=0.02) print("Total DCF Value:", dcf_result["total_dcf_value"])

Dividend Discount Model (DDM)

import efin

Estimate the stock price of KO using a 3% dividend growth rate and a 10% discount rate.

ddm_price = efin.dividend_discount_model("KO", growth_rate=0.03, discount_rate=0.1) print("DDM Price for KO:", ddm_price)

Comparable Company Analysis

import efin

Compare AAPL against MSFT and GOOGL using the trailing P/E multiple.

result = efin.comparable_company_analysis("AAPL", ["MSFT", "GOOGL"], multiple="trailingPE") print(result)

Residual Income Model (RIM)

import efin

Estimate intrinsic value for AAPL using a 10% cost of equity, 5% growth rate, over 5 periods.

rim_value = efin.residual_income_model("AAPL", cost_of_equity=0.10, growth_rate=0.05, forecast_period=5) print("Residual Income Value:", rim_value)

Forecasting Unified Forecast (Linear Regression)

import efin

Forecast AAPL prices for the next 30 days using a linear regression approach.

forecast_df = efin.forecast("AAPL", forecast_period=30, start_date="2010-01-01") print(forecast_df)

Auto ARIMA Grid Forecast

import efin

Forecast AAPL prices for the next 5 days using a grid search over ARIMA parameters.

forecast_df, best_order, best_aic = efin.auto_arima_grid_forecast("AAPL", forecast_period=5, start_date="2010-01-01") print("Best ARIMA order:", best_order, "with AIC:", best_aic) print(forecast_df)

Risk Metrics

import efin

Calculate the volatility and Sharpe ratio for AAPL.

volatility = efin.calculate_volatility("AAPL", start_date="2020-01-01") sharpe = efin.sharpe_ratio("AAPL", risk_free_rate=0.01, start_date="2020-01-01") print("Volatility:", volatility) print("Sharpe Ratio:", sharpe) Portfolio Analysis python Copy import efin

Download adjusted close prices for AAPL and MSFT.

prices = efin.download_adj_close(["AAPL", "MSFT"], start_date="2020-01-01") print(prices.head())

Compute a basic equal-weighted portfolio allocation.

returns = prices.pct_change().dropna() weights = efin.markowitz_portfolio(returns) print("Portfolio Weights:", weights) Data Caching python Copy import efin

Initialize caching for 1 hour to speed up repeated data retrieval.

efin.initialize_cache(expire_after=3600)

Visualization

import efin from efin.visualization import plot_forecast import pandas as pd import numpy as np

Generate sample historical data

dates = pd.date_range("2020-01-01", periods=50) history = pd.Series(np.random.randn(50).cumsum(), index=dates)

Generate sample forecast data for 10 days

forecast_dates = pd.date_range("2020-02-20", periods=10) forecast_values = pd.Series(np.random.randn(10).cumsum(), index=forecast_dates)

plot_forecast(history, forecast_values, title="Historical vs Forecast")

Command-Line Interface (CLI) From the terminal, run:

Calculate DCF valuation for AAPL over 5 years.

python -m efin.cli dcf AAPL --years 5 --discount_rate 0.10 --growth_rate 0.05 --terminal_growth_rate 0.02

Forecast stock prices for AAPL using linear regression (default).

python -m efin.cli forecast AAPL --model linear --period 30

Forecast stock prices for AAPL using grid search ARIMA.

python -m efin.cli forecast AAPL --model grid --period 5

Contributing Contributions are welcome! If you have suggestions, bug reports, or improvements, please open an issue or submit a pull request on the GitHub repository:https://github.com/ebeirne/efin

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

Contact For questions or feedback, please contact [e-mail]