pfisca 0.1.0

A comprehensive financial planning tool

Prism

A Python-based financial planning library for projecting net worth over time using Monte Carlo simulation. This tool helps individuals and families model their financial future by simulating various income, expense, investment, and tax scenarios across multiple years, with a focus on FIRE (Financial Independence, Retire Early) planning.

Table of Contents

• Prism
  • Table of Contents
  • Features
  • Quick Start
    • Installation
      • From Source
      • Using pip (when published)
    • Basic Usage
    • Using as a Python Library
      • Example: Calculate Stock Metrics
      • Example: Risk Calculations
  • Documentation
    • Quick Links
    • Documentation Sections
  • Examples
  • Contributing
    • Development Setup
    • Code Style
  • Requirements
  • License
  • Future Enhancements
  • Acknowledgments

Features

• 💰 Income Modeling: Multiple sources (salaries, bonuses, RSUs) with growth and variability
• 📊 Tax Calculations: Federal, state, and payroll taxes with proper filing status
• 💸 Expense Tracking: Fixed, inflation-adjusted, or percentage-based expenses
• 📈 Investment Simulation: Monte Carlo simulation with correlated returns
• 🏦 Portfolio Management: Real market data integration for individual stocks
• 📉 Stock Analysis: Comprehensive metrics (alpha, beta, Sharpe, VaR, drawdown, etc.)
• 🔄 Trading: High-performance backtesting framework for trading strategies
• 🔥 FIRE Planning: Calculate timelines for Coast, Lean, Chubby, and Fat FIRE
• 💵 Paycheck Calculations: Detailed per-paycheck breakdowns with taxes and deductions

Quick Start

Installation

From Source

# Clone the repository
git clone https://github.com/adityahemanth/prism.git
cd prism

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Using pip (when published)

pip install prism

Basic Usage

Create a simple config file:

# my_config.yaml
persons:
  - name: "Person 1"
    income_sources:
      - type: "base_salary"
        base_amount: 200000.0

Run the simulation:

python src/main.py my_config.yaml

This uses smart defaults for taxes, retirement, expenses, and investments. See Getting Started Guide for details.

Using as a Python Library

from prism import FinanceProjection

# Load configuration and run simulation
projection = FinanceProjection.from_config("config.yaml")
results = projection.run_simulation()
median_net_worth = results['net_worth_percentiles'][50]
print(f"Median net worth: ${median_net_worth:,.2f}")

Example: Calculate Stock Metrics

from prism import calculate_stock_metrics, format_stock_metrics

# Calculate comprehensive metrics for a stock
metrics = calculate_stock_metrics("AAPL", years=5, benchmark_ticker="SPY")

# Print formatted output
print(format_stock_metrics(metrics))

# Access individual metrics
print(f"Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"Beta: {metrics.beta:.2f}")
print(f"Max Drawdown: {metrics.max_drawdown:.2%}")

Example: Risk Calculations

import pandas as pd
from prism import (
    calculate_volatility,
    calculate_max_drawdown,
    calculate_sharpe_ratio
)

# Daily returns
returns = pd.Series([0.01, -0.02, 0.03, -0.01, 0.02] * 50)

# Calculate risk metrics
volatility = calculate_volatility(returns, annualized=True, periods_per_year=252)
max_dd = calculate_max_drawdown(returns)
sharpe = calculate_sharpe_ratio(returns, risk_free_rate=0.02, periods_per_year=252)

print(f"Volatility: {volatility:.2%}")
print(f"Max Drawdown: {max_dd:.2%}")
print(f"Sharpe Ratio: {sharpe:.2f}")

Documentation

📚 Full Documentation - Complete documentation index

Quick Links

• Getting Started - Installation and basic usage
• Configuration Guide - Creating and customizing config files
• Financial Metrics Guide - Comprehensive guide to metrics (Sharpe, Beta, VaR, etc.)
• Risk Calculations Guide - Step-by-step risk analysis
• API Reference - Complete API documentation
• Examples - Code examples

Documentation Sections

• Guides - Step-by-step guides for common tasks
  • Configuration
  • Projections
  • FIRE Planning
  • Financial Metrics
  • Risk Calculations
• Topics - Deep dives into specific features
  • Trading
  • Portfolio Management
  • Stock Metrics
  • Tax Calculations
• API Reference - Complete API documentation
• Reference - Methodology and configuration reference

Examples

Check out the examples directory for complete working examples:

• library_usage.py - Basic library usage
• trading_example.py - Simple backtesting example
• advanced_trading_example.py - Advanced backtesting strategies
• portfolio_holdings_example.py - Portfolio analysis
• stock_metrics_example.py - Stock metrics calculation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/adityahemanth/prism.git
cd prism
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=html

Code Style

• Follow PEP 8 style guidelines
• Use type hints where appropriate
• Write tests for new features
• Update documentation for API changes

Requirements

• Python 3.9+
• NumPy >= 2.0.0
• pandas >= 2.0.0
• PyYAML >= 6.0.0
• yfinance >= 0.2.0
• scipy >= 1.10.0
• vectorbt >= 0.25.0 (for trading/backtesting)

See requirements.txt for the complete list.

License

This project is licensed under the MIT License. See the LICENSE file for details (if available).

Future Enhancements

For a comprehensive list of planned features, see TODO.md.

Acknowledgments

• Built with NumPy and pandas for numerical computing
• Market data provided by yfinance
• Backtesting powered by vectorbt

---

Note: This library is for educational and personal financial planning purposes. Always consult with a qualified financial advisor for professional financial advice.