🚀 AlgoSystem

A batteries-included Python library for algorithmic trading backtesting and beautiful, interactive dashboard visualization.

Transform your trading strategy performance analysis with professional-grade dashboards that rivals institutional trading platforms.

---

✨ Features

• 🔄 Simple Backtesting: Run backtests with just a price series - no complex strategy definitions required
• 📊 Interactive Dashboards: Generate beautiful HTML dashboards with 20+ metrics and charts
• 🎨 Visual Dashboard Editor: Drag-and-drop interface for customizing dashboard layouts
• 📈 Comprehensive Analytics: Performance metrics, risk analysis, rolling statistics, and more
• 🆚 Benchmark Comparison: Compare strategies against market benchmarks with alpha/beta analysis
• ⚙️ Flexible Configuration: JSON-based system for complete dashboard customization
• 💻 CLI Tools: Command-line interface for quick dashboard generation
• 🌐 Standalone Dashboards: Export self-contained HTML files that work offline

---

📦 Installation

Quick Install (Recommended)

bash pip install algosystem

Development Installation

```bash

Clone the repository

git clone https://github.com/yourusername/algosystem.git cd algosystem

poetry install ```

Requirements

• Python 3.9+
• pandas >= 2.0.0
• numpy >= 1.24.0
• Works on Windows, macOS, and Linux

---

🚀 Quick Start

1. Basic Backtesting

```python import pandas as pd from algosystem import Engine

Load your strategy data (price series)

data = pd.readcsv('strategyprices.csv', indexcol=0, parsedates=True)

Run backtest and generate dashboard

engine = Engine(data) results = engine.run() dashboardpath = engine.generatedashboard()

print(f"Dashboard ready: {dashboard_path}") ```

2. Using the CLI

```bash

Generate dashboard from CSV

algosystem dashboard strategy_data.csv

Launch visual dashboard editor

algosystem launch

Create standalone dashboard

algosystem dashboard strategydata.csv --output-file mydashboard.html ```

3. Compare with Benchmark

```python from algosystem import Engine

Load strategy and benchmark data

strategy = pd.readcsv('strategy.csv', indexcol=0, parsedates=True) benchmark = pd.readcsv('sp500.csv', indexcol=0, parsedates=True)

Run comparison

engine = Engine(strategy, benchmark=benchmark) results = engine.run()

Results include alpha, beta, correlation, etc.

print(f"Alpha: {results['metrics']['alpha']:.4f}") print(f"Beta: {results['metrics']['beta']:.4f}") print(f"Sharpe Ratio: {results['metrics']['sharpe_ratio']:.4f}") ```

---

📚 Complete Usage Guide

Understanding Your Data

AlgoSystem works with price series (portfolio values over time), not individual trades or signals.

Data Format Requirements

Your CSV should look like this:

Date,Portfolio_Value 2020-01-01,100000.00 2020-01-02,100150.25 2020-01-03,99875.50 ...

Loading Data

```python import pandas as pd

From CSV

data = pd.readcsv('portfolio.csv', indexcol=0, parse_dates=True)

From pandas DataFrame

dates = pd.date_range('2020-01-01', periods=1000, freq='D') prices = 100 * (1 + pd.Series(returns)).cumprod() data = pd.Series(prices, index=dates)

From multiple columns (use first column)

data = pd.readcsv('multicolumn.csv', indexcol=0, parsedates=True) strategydata = data['PortfolioValue'] # Select specific column ```

Core Engine Features

1. Basic Backtesting

```python from algosystem import Engine

Initialize engine

engine = Engine( data=portfolioseries, startdate='2020-01-01', # Optional: filter date range enddate='2023-12-31', # Optional: filter date range initialcapital=100000 # Optional: set starting capital )

Run backtest

results = engine.run()

Access results

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

2. Benchmark Analysis

```python

Compare against benchmark

engine = Engine(strategydata, benchmark=benchmarkdata) results = engine.run()

Benchmark-specific metrics

benchmarkmetrics = { 'alpha': results['metrics']['alpha'], 'beta': results['metrics']['beta'], 'correlation': results['metrics']['correlation'], 'trackingerror': results['metrics']['trackingerror'], 'informationratio': results['metrics']['information_ratio'] } ```

3. Dashboard Generation

```python

Generate full dashboard

dashboardpath = engine.generatedashboard( outputdir='./mydashboard', openbrowser=True, # Auto-open in browser configpath='custom_config.json' # Use custom layout )

Generate standalone dashboard

standalonepath = engine.generatestandalonedashboard( 'portfolioanalysis.html' ) ```

Advanced Usage

Custom Dashboard Configuration

Create a dashboard_config.json:

json { "metrics": [ { "id": "total_return", "type": "Percentage", "title": "Total Return", "value_key": "total_return", "position": {"row": 0, "col": 0} }, { "id": "sharpe_ratio", "type": "Value", "title": "Sharpe Ratio", "value_key": "sharpe_ratio", "position": {"row": 0, "col": 1} } ], "charts": [ { "id": "equity_curve", "type": "LineChart", "title": "Portfolio Growth", "data_key": "equity_curve", "position": {"row": 1, "col": 0}, "config": { "y_axis_label": "Portfolio Value ($)", "percentage_format": false } }, { "id": "monthly_returns", "type": "HeatmapTable", "title": "Monthly Returns", "data_key": "monthly_returns", "position": {"row": 1, "col": 1}, "config": {} } ], "layout": { "max_cols": 2, "title": "My Custom Dashboard" } }

Working with Returns vs Prices

```python

If you have returns instead of prices

returnsseries = pd.readcsv('returns.csv', indexcol=0, parsedates=True)

Convert to price series

initialvalue = 100000 priceseries = initialvalue * (1 + returnsseries).cumprod()

Run backtest

engine = Engine(price_series) results = engine.run() ```

Risk Analysis

```python

Access detailed risk metrics

riskmetrics = { 'volatility': results['metrics']['annualized_volatility'], 'var95': results['metrics']['var95'], 'cvar95': results['metrics']['cvar95'], 'maxdrawdown': results['metrics']['maxdrawdown'], 'sortinoratio': results['metrics']['sortinoratio'], 'calmarratio': results['metrics']['calmar_ratio'] }

Rolling metrics for time series analysis

rollingdata = results['plots'] rollingsharpe = rollingdata['rollingsharpe'] rollingvolatility = rollingdata['rollingvolatility'] drawdownseries = rollingdata['drawdownseries'] ```

CLI Reference

Dashboard Commands

```bash

Basic dashboard generation

algosystem dashboard portfolio.csv

With custom output location

algosystem dashboard portfolio.csv --output-dir ./results

Standalone dashboard

algosystem dashboard portfolio.csv --output-file analysis.html

Include benchmark comparison

algosystem dashboard portfolio.csv --benchmark sp500.csv

Use custom configuration

algosystem dashboard portfolio.csv --config custom_layout.json ```

Dashboard Editor

```bash

Launch web-based editor

algosystem launch

Launch on specific port

algosystem launch --port 8080

Load existing configuration

algosystem launch --config existing_config.json

Save configuration to specific location

algosystem launch --save-config ./configs/my_layout.json ```

Configuration Management

```bash

Create new configuration file

algosystem create-config my_config.json

View configuration contents

algosystem show-config my_config.json

List all configurations

algosystem list-configs ```

---

🛠️ Developer Tutorial

Understanding the Architecture

AlgoSystem follows a modular architecture designed for extensibility:

``` ┌─────────────────────────────────────────────────────────────┐ │ AlgoSystem Architecture │ └─────────────────────────────────────────────────────────────┘

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Data Input │ │ Engine Core │ │ Dashboard │ │ │ │ │ │ Generator │ │ • CSV Files │ ── │ • Backtesting │ ── │ • HTML Export │ │ • Pandas Series │ │ • Metrics Calc │ │ • Standalone │ │ • Price Data │ │ • Risk Analysis │ │ • Interactive │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ ┌─────────────────┐ │ │ │ Analysis │ │ │ │ Modules │ │ │ │ │ │ └────────────▶│ • Performance │◀────────────┘ │ • Risk │ │ • Portfolio │ └─────────────────┘ │ ┌─────────────────┐ │ Web Editor │ │ │ │ • Flask App │ │ • Drag & Drop │ │ • Live Preview │ └─────────────────┘ ```

Core Components

1. Engine Class (algosystem.backtesting.Engine)

The main interface for backtesting:

```python class Engine: def init(self, data, benchmark=None, startdate=None, enddate=None, initial_capital=None): """ Initialize backtesting engine.

    Parameters:
    -----------
    data : pd.Series or pd.DataFrame
        Portfolio price series
    benchmark : pd.Series, optional
        Benchmark price series for comparison
    start_date : str or datetime, optional
        Start date for analysis
    end_date : str or datetime, optional
        End date for analysis
    initial_capital : float, optional
        Initial portfolio value
    """

def run(self) -> dict:
    """Run backtest and return results."""

def generate_dashboard(self, output_dir=None, 
                      config_path=None) -> str:
    """Generate interactive HTML dashboard."""

```

2. Metrics Module (algosystem.analysis.metrics)

Comprehensive performance calculations:

```python

Key functions

def calculate_metrics(strategy, benchmark=None) -> dict: """Calculate static performance metrics."""

def calculatetimeseries_data(strategy, benchmark=None) -> dict: """Calculate rolling metrics and time series."""

def rolling_sharpe(returns, window=30) -> pd.Series: """Calculate rolling Sharpe ratio.""" ```

3. Dashboard Generator (algosystem.backtesting.dashboard)

Creates interactive visualizations:

```python def generatedashboard(engine, outputdir=None, config_path=None) -> str: """Generate complete dashboard with configuration."""

def generatestandalonedashboard(engine, output_path=None) -> str: """Create self-contained HTML file.""" ```

Creating Custom Metrics

Add your own performance metrics:

```python

In algosystem/analysis/custom_metrics.py

def calculatecustommetric(returns): """Calculate a custom performance metric.""" # Your custom calculation here return custom_value

Register with the system

from algosystem.analysis.metrics import calculate_metrics

Extend the metrics function

originalcalculatemetrics = calculate_metrics

def enhancedcalculatemetrics(strategy, benchmark=None): metrics = originalcalculatemetrics(strategy, benchmark)

# Add custom metric
returns = strategy.pct_change().dropna()
metrics['custom_metric'] = calculate_custom_metric(returns)

return metrics

Replace the original function

algosystem.analysis.metrics.calculatemetrics = enhancedcalculate_metrics ```

Extending Dashboard Components

Custom Chart Types

Create new visualization types:

```python

In algosystem/backtesting/dashboard/charts/custom_chart.py

def createcustomchart(data, config): """Create a custom chart component.""" return { 'type': 'CustomChart', 'data': formatdatafor_chart(data), 'config': config }

Register in available_components.py

AVAILABLECHARTS.append({ "id": "customchart", "type": "CustomChart", "title": "My Custom Chart", "datakey": "customdata", "description": "Description of custom chart", "category": "custom" }) ```

Custom Metrics

Add new metric types:

```python

In available_components.py

AVAILABLEMETRICS.append({ "id": "mymetric", "type": "Percentage", "title": "My Custom Metric", "valuekey": "mycustom_metric", "description": "Description of my metric", "category": "custom" }) ```

Plugin Architecture

Create plugins for AlgoSystem:

```python

Create a plugin file: algosystempluginexample.py

class AlgoSystemPlugin: def init(self): self.name = "Example Plugin" self.version = "1.0.0"

def register_metrics(self):
    """Register custom metrics."""
    return {
        'plugin_metric': self.calculate_plugin_metric
    }

def register_charts(self):
    """Register custom charts."""
    return {
        'plugin_chart': self.create_plugin_chart
    }

def calculate_plugin_metric(self, data):
    """Custom metric calculation."""
    return data.std() * 252 ** 0.5

def create_plugin_chart(self, data, config):
    """Custom chart creation."""
    return {
        'type': 'PluginChart',
        'data': data.to_dict(),
        'config': config
    }

Use the plugin

plugin = AlgoSystemPlugin()

Register plugin with AlgoSystem...

```

Testing Your Extensions

Create tests for custom components:

```python

tests/testcustommetrics.py

import pytest import pandas as pd import numpy as np from algosystem.analysis.custommetrics import calculatecustom_metric

def testcustommetric(): # Create test data dates = pd.date_range('2020-01-01', periods=100) returns = pd.Series(np.random.normal(0.001, 0.02, 100), index=dates)

# Test metric calculation
result = calculate_custom_metric(returns)

# Assertions
assert isinstance(result, float)
assert not np.isnan(result)
assert result > 0  # or whatever makes sense for your metric

Run tests

pytest tests/testcustommetrics.py

```

Performance Optimization

Efficient Data Processing

```python

Use vectorized operations

def efficientrollingcalculation(data, window=252): """Efficient rolling calculation using pandas.""" return data.rolling(window).apply( lambda x: x.std() * np.sqrt(252), raw=True # Use raw numpy arrays for speed )

Cache expensive calculations

from functools import lru_cache

@lrucache(maxsize=128) def cachedcomplexcalculation(datahash, window): """Cache expensive calculations.""" # Complex calculation here pass ```

Memory Management

```python

Process large datasets in chunks

def processlargedataset(data, chunk_size=10000): """Process large datasets efficiently.""" results = []

for i in range(0, len(data), chunk_size):
    chunk = data.iloc[i:i+chunk_size]
    result = process_chunk(chunk)
    results.append(result)

    # Clean up memory
    del chunk

return pd.concat(results)

```

Best Practices

1. Error Handling

```python def robustmetriccalculation(data): """Calculate metric with proper error handling.""" try: if data.empty: return 0.0

    if len(data) < 30:
        logger.warning("Insufficient data for metric calculation")
        return np.nan

    result = calculate_metric(data)

    if np.isnan(result) or np.isinf(result):
        return 0.0

    return result

except Exception as e:
    logger.error(f"Error calculating metric: {e}")
    return np.nan

```

2. Configuration Validation

```python def validatedashboardconfig(config): """Validate dashboard configuration.""" required_fields = ['metrics', 'charts', 'layout']

for field in required_fields:
    if field not in config:
        raise ValueError(f"Missing required field: {field}")

# Validate metrics
for metric in config['metrics']:
    if 'id' not in metric:
        raise ValueError("Metric missing required 'id' field")
    if 'position' not in metric:
        raise ValueError(f"Metric {metric['id']} missing position")

return True

```

3. Logging

```python import logging

Set up logging

logger = logging.getLogger('algosystem') handler = logging.StreamHandler() formatter = logging.Formatter( '%(asctime)s - %(name)s - %(levelname)s - %(message)s' ) handler.setFormatter(formatter) logger.addHandler(handler) logger.setLevel(logging.INFO)

Use throughout your code

logger.info("Starting backtest...") logger.warning("Low data quality detected") logger.error("Failed to calculate metric") ```

---

🎨 Visual System Overview

Data Flow Diagram

```mermaid graph TD A["Portfolio Data
CSV/DataFrame"] --> B["Engine.run()"] B --> C["Metrics Calculation"] B --> D["Time Series Analysis"] B --> E["Risk Assessment"]

C --> F["Performance Metrics<br/>• Total Return<br/>• Sharpe Ratio<br/>• Max Drawdown"]
D --> G["Rolling Analytics<br/>• Rolling Sharpe<br/>• Rolling Volatility<br/>• Drawdown Series"]
E --> H["Risk Metrics<br/>• VaR/CVaR<br/>• Skewness<br/>• Sortino Ratio"]

F --> I["Dashboard Generator"]
G --> I
H --> I

I --> J["Configuration<br/>dashboard_config.json"]
J --> K["HTML Dashboard<br/>Interactive Charts<br/>& Metrics"]

L["Benchmark Data<br/>Optional"] --> B
M["Custom Config<br/>Optional"] --> J

```

Dashboard Component Architecture

```mermaid graph LR A[Dashboard Layout] --> B[Metrics Section] A --> C[Charts Section]

B --> D[Metric Row 1<br/>4 columns max]
B --> E[Metric Row 2<br/>4 columns max]

C --> F[Chart Row 1<br/>2 columns max]
C --> G[Chart Row 2<br/>2 columns max]

D --> H[Performance<br/>Metrics]
D --> I[Risk<br/>Metrics]
D --> J[Ratio<br/>Metrics]
D --> K[Trade<br/>Statistics]

F --> L[Equity Curve<br/>Line Chart]
F --> M[Drawdown<br/>Area Chart]
G --> N[Rolling Metrics<br/>Line Chart]
G --> O[Monthly Returns<br/>Heatmap]

```

CLI Command Structure

```mermaid graph TD A[algosystem] --> B[dashboard] A --> C[launch] A --> D[create-config] A --> E[show-config] A --> F[list-configs]

B --> G[strategy.csv<br/>Input File]
B --> H[--output-dir<br/>Output Directory]
B --> I[--benchmark<br/>Benchmark File]
B --> J[--config<br/>Config File]

C --> K[--port<br/>Server Port]
C --> L[--host<br/>Server Host]
C --> M[--config<br/>Load Config]
C --> N[--save-config<br/>Save Location]

D --> O[output.json<br/>New Config]
D --> P[--based-on<br/>Template Config]

```

Metric Categories Visualization

mermaid mindmap root((AlgoSystem<br/>Metrics)) Performance Total Return Annualized Return Volatility CAGR Risk Max Drawdown VaR (95%, 99%) CVaR/Expected Shortfall Downside Deviation Skewness Kurtosis Ratios Sharpe Ratio Sortino Ratio Calmar Ratio Information Ratio Trade Statistics Win Rate Best/Worst Month Positive/Negative Days Average Returns Benchmark Relative Alpha Beta Correlation Tracking Error Capture Ratios

Chart Types Available

| Chart Type | Description | Use Case | |------------|-------------|----------| | 📈 Line Chart | Time series visualization | Equity curves, rolling metrics | | 🔥 Heatmap Table | Color-coded data grid | Monthly/yearly returns | | 📊 Bar Chart | Categorical comparisons | Annual performance | | 🌊 Area Chart | Filled line charts | Drawdown visualization | | 📉 Candlestick | OHLC price data | Market analysis (future) |

Color Scheme & Styling

```css /* AlgoSystem Color Palette */ :root { --primary-blue: #2E86AB; --success-green: #2ECC71; --warning-orange: #F39C12; --danger-red: #E74C3C; --dark-gray: #2C3E50; --light-gray: #ECF0F1; --purple: #9B59B6; --teal: #1ABC9C; }

/* Positive/Negative Indicators */ .positive { color: var(--success-green); } .negative { color: var(--danger-red); }

/* Chart Colors */ .equity-curve { color: var(--primary-blue); } .drawdown { color: var(--danger-red); } .rolling-metrics { color: var(--purple); } .benchmark { color: var(--teal); } ```

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

```bash

Fork and clone

git clone https://github.com/yourusername/algosystem.git cd algosystem

Set up development environment

poetry install --with dev

Run tests

pytest

Run linting

black algosystem tests flake8 algosystem tests

Start development server

poetry run algosystem launch --debug ```

---

📄 License

MIT License - see LICENSE file for details.

---

🔗 Links & Resources

• 📦 PyPI Package: pypi.org/project/algosystem
• 📚 Documentation: algosystem.readthedocs.io
• 🐙 GitHub Repository: github.com/yourusername/algosystem
• 🐛 Issue Tracker: github.com/yourusername/algosystem/issues
• 💬 Discussions: github.com/yourusername/algosystem/discussions

---

🏆 Acknowledgments

Built with ❤️ for the algorithmic trading community.

Special thanks to: - QuantStats for inspiration on metrics - Plotly for interactive charting capabilities - Flask for the web-based editor - The Python finance community for continuous feedback and contributions

---

Happy trading! 📈