# Functional Overview

The `market-analysis` toolkit is designed to streamline the process of retrieving, caching, and analyzing financial market data. It bridges the gap between raw data providers and actionable financial insights by providing a robust framework for performance metrics and visualization.

## Core Workflow

The project follows a structured data processing sequence:

1.  **Data Fetching**: Interface with Yahoo Finance (`yfinance`) to retrieve historical OHLCV data.
2.  **Local Caching**: Persistence layer using Parquet files to minimize network requests and improve performance.
3.  **Asset Modeling**: Encapsulation of raw data into high-level `Asset` objects that handle statistical calculations.
4.  **Analysis**: Computation of key performance indicators like CAGR, Volatility, and Drawdowns.
5.  **Visualization**: Generation of multi-panel charts for visual correlation and trend analysis.

---

## Data Acquisition & Caching

The toolkit uses a "Fetch-Through" cache strategy managed by the `CacheManager`:

- **Local Storage**: Data is stored in the `cache_history/` directory using the Apache Parquet format (via `pyarrow`), providing high compression and fast read/write speeds.
- **Cache Validation**: The system checks the modification time of cached files. If the data is older than the configured `CACHE_MAX_AGE` (default: 1 day), it triggers a background refresh from Yahoo Finance.
- **Concurrent Fetching**: When loading multiple tickers, the `DataFetcher` utilizes a thread pool (`MAX_WORKERS`) to download data in parallel, significantly reducing wait times.

## Performance Metrics

The `Asset` class computes several critical financial metrics:

- **Returns**: Logarithmic and simple returns for various frequencies (Daily, Monthly, Yearly).
- **Risk Metrics**:
  - **Volatility**: Annualized standard deviation of returns.
  - **Maximum Drawdown**: The peak-to-trough decline during a specific period.
  - **Rolling Metrics**: Rolling volatility and Sharpe ratio (default 63-day window) to visualize risk evolution over time.
- **Growth Metrics**: Compound Annual Growth Rate (CAGR) and total cumulative returns.

## Visualization Engine

The toolkit generates a comprehensive five-panel chart for each asset:

1.  **Price Chart**: Raw closing prices, with optional logarithmic scaling.
2.  **Cumulative Returns**: Growth of a hypothetical $1 investment.
3.  **Drawdown Map**: Visualizes the depth and duration of "underwater" periods.
4.  **Rolling Volatility**: Tracks changes in asset risk profile over time.
5.  **Rolling Sharpe Ratio**: Displays the risk-adjusted return trend.

## Interface Options

### Command Line Interface (CLI)
Designed for quick checks and terminal-based analysis. It provides a summarized text report of an asset's performance directly in the console.

### Python API
Designed for integration into larger research projects or Jupyter notebooks. It offers full programmatic access to the `Asset` and `DataFetcher` classes, allowing for custom data manipulation and advanced plotting.