Metadata-Version: 2.4
Name: finpie
Version: 0.1.0
Summary: A comprehensive Python library for Brazilian financial data analysis and quantitative research
Home-page: https://github.com/enzobjmendonca/finpie
Author: Enzo Mendonça
Author-email: enzobjmendonca@gmail.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: yfinance>=0.2.0
Requires-Dist: pandas-datareader>=0.10.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: pytest>=7.3.0
Requires-Dist: black>=23.0.0
Requires-Dist: flake8>=6.0.0
Requires-Dist: mypy>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: jupyter>=1.0.0
Requires-Dist: notebook>=6.0.0
Requires-Dist: ipykernel>=6.0.0
Requires-Dist: alpha_vantage>=2.3.1
Requires-Dist: torch>=2.1.0
Requires-Dist: transformers>=4.36.0
Requires-Dist: datasets>=2.16.0
Requires-Dist: peft>=0.7.0
Requires-Dist: bitsandbytes>=0.41.0
Requires-Dist: MetaTrader5>=5.0.4993; platform_system == "Windows"
Provides-Extra: dev
Requires-Dist: pytest>=7.3.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0.0; extra == "notebooks"
Requires-Dist: notebook>=6.0.0; extra == "notebooks"
Requires-Dist: ipykernel>=6.0.0; extra == "notebooks"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# finpie

A Python library for quantitative finance, providing tools for data handling, analysis, and trading strategies.

## Installation

### Regular Installation
```bash
pip install finpie
```

### Development Setup

1. Create a virtual environment:
   ```bash
   # Windows
   python -m venv venv
   
   # Linux/MacOS
   python3 -m venv venv
   ```

2. Activate the virtual environment:
   ```bash
   # Windows
   .\venv\Scripts\activate
   
   # Linux/MacOS
   source venv/bin/activate
   ```

3. Install in development mode:
   ```bash
   # Install in development mode with all dependencies
   pip install -e .
   
   # Install with development tools
   pip install -e ".[dev]"
   
   # Install with notebook support
   pip install -e ".[notebooks]"
   
   # Install with both development tools and notebook support
   pip install -e ".[dev,notebooks]"
   ```

4. Running Jupyter Notebooks:
   ```bash
   # Start Jupyter
   jupyter notebook
   
   # Navigate to the finpie/notebooks directory
   # Open the desired notebook (e.g., data_examples.ipynb)
   ```

## Quick Start

### Basic Time Series Usage

```python
from finpie.data import TimeSeries, TimeSeriesMetadata
import pandas as pd
from datetime import datetime

# Create a simple time series
data = pd.DataFrame({
    'open': [100, 101, 102],
    'high': [103, 104, 105],
    'low': [99, 100, 101],
    'close': [102, 103, 104],
    'volume': [1000, 1100, 1200]
}, index=pd.date_range('2024-01-01', periods=3))

metadata = TimeSeriesMetadata(
    symbol='AAPL',
    source='yahoo',
    start_date=datetime(2024, 1, 1),
    end_date=datetime(2024, 1, 3),
    frequency='1D',
    currency='USD',
    additional_info={'sector': 'Technology'}
)

ts = TimeSeries(data, metadata)

# Basic operations
returns = ts.returns()  # Calculate returns
resampled = ts.resample('1W')  # Resample to weekly frequency
rolling_stats = ts.rolling(window=20)  # Calculate rolling statistics
```

### Statistical Analysis

```python
from finpie.analytics import StatisticalAnalytics

# Create analytics instance
analytics = StatisticalAnalytics(ts, column='close')

# Calculate various statistics
zscore = analytics.zscore(window=20)  # Calculate z-scores
half_life = analytics.half_life()  # Calculate half-life of mean reversion
hurst = analytics.hurst_exponent()  # Calculate Hurst exponent
spread = analytics.spread_to_ma(window=20)  # Calculate spread to moving average

# Generate trading signals
signals = analytics.trading_signals(zscore_threshold=2.0, window=20)
```

### Ratio Analysis

```python
from finpie.data import RatioTimeSeries

# Create ratio time series (e.g., for pair trading)
ratio_ts = RatioTimeSeries(numerator_ts, denominator_ts)

# Access the ratio data
ratio_data = ratio_ts.data

# Create analytics instance for the ratio
ratio_analytics = StatisticalAnalytics(ratio_ts, column='ratio')

# Calculate statistics
zscore = ratio_analytics.zscore()
mean_reversion = ratio_analytics.spread_to_ma() / ratio_ts.data['ratio']
signals = ratio_analytics.trading_signals()
```

### Spread Analysis

```python
from finpie.data import SpreadTimeSeries

# Create spread time series (e.g., for statistical arbitrage)
spread_ts = SpreadTimeSeries(series1_ts, series2_ts)

# Access the spread data and hedge ratio
spread_data = spread_ts.data
hedge_ratio = spread_ts.hedge_ratio

# Create analytics instance for the spread
spread_analytics = StatisticalAnalytics(spread_ts, column='spread')

# Calculate statistics
zscore = spread_analytics.zscore()
half_life = spread_analytics.half_life()
hurst = spread_analytics.hurst_exponent()
signals = spread_analytics.trading_signals()
```

### Multiple Time Series Analysis

```python
from finpie.data import MultiTimeSeries
from finpie.data.service import DataService

ds = DataService.create_default_service()
ts1 = = service.get_close_prices(
    'AAPL',
    'yahoo_finance',
    '2025-01-01',
    '2025-01-10',
    interval='1d',
)
ts2 = = service.get_close_prices(
    'GOOGL',
    'yahoo_finance',
    '2025-01-01',
    '2025-01-10',
    interval='1d',
)
ts2 = = service.get_close_prices(
    'MSFT',
    'yahoo_finance',
    '2025-01-01',
    '2025-01-10',
    interval='1d',
)
# Create multi time series for portfolio analysis
multi_ts = MultiTimeSeries([ts1, ts2, ts3])

# Calculate correlation and covariance
correlation = multi_ts.correlation()
covariance = multi_ts.covariance()

# Calculate portfolio returns
weights = {'AAPL': 0.4, 'MSFT': 0.3, 'GOOGL': 0.3}
portfolio_returns = multi_ts.portfolio_returns(weights)

# Calculate rolling correlations
rolling_correlations = multi_ts.rolling_correlation(window=20)
```

## Project Structure

```
finpie/
├── data/           # Data handling module
├── analytics/      # Analytics and modeling module
├── datasource/     # Data request module
├── notebooks/      # Usage examples and tutorials
└── docs/           # Documentation
```

## Features

- **Time Series Management**
  - Flexible data structure with metadata support
  - Built-in data validation and alignment
  - Support for various frequencies and resampling
  - Comprehensive statistical calculations

- **Statistical Analysis**
  - Z-score calculations
  - Mean reversion metrics (half-life, Hurst exponent)
  - Moving average analysis
  - Trading signal generation

- **Specialized Time Series**
  - Ratio analysis for pair trading
  - Spread analysis for statistical arbitrage
  - Multi-time series for portfolio analysis

## Contributing

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

## License

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