Add normalized position scaling

Author: MDUYN

docusaurus/docs/Getting Started/positions.md

@@ -39,16 +39,14 @@ def apply_strategy(self, algorithm, market_data):
     for position in positions:
         print(f"Position: {position.symbol}")
         print(f"Amount: {position.amount}")
-        print(f"Entry Price: {position.entry_price}")
-        print(f"Current Value: {position.current_value}")
 ```
 
 ### Get Specific Position
 
 ```python
 def apply_strategy(self, algorithm, market_data):
     # Get position for specific symbol
-    btc_position = algorithm.get_position("BTC/USDT")
+    btc_position = algorithm.get_position("BTC")
 
     if btc_position:
         print(f"BTC Position: {btc_position.amount} BTC")
@@ -75,13 +73,14 @@ def analyze_position(self, position, market_data):
 
     print(f"Symbol: {symbol}")
     print(f"Amount: {amount}")
-    print(f"Entry: ${entry_price:.2f}")
-    print(f"Current: ${current_price:.2f}")
-    print(f"P&L: ${unrealized_pnl:.2f} ({pnl_percentage:.2f}%)")
 ```
 
 ## Position Management Strategies
 
+:::tip Multi-Symbol Strategy Allocation
+When trading multiple symbols simultaneously, ensure your total position size allocations don't exceed 100% of your portfolio. The framework will automatically scale orders proportionally if needed, but it's best practice to plan allocations that fit within available funds (e.g., 5 symbols × 20% = 100%).
+:::
+
 ### Profit Taking
 
 ```python
@@ -142,6 +141,58 @@ class StopLossStrategy(TradingStrategy):
 
 ### Position Sizing
 
+The framework provides a `PositionSize` class to define how much capital to allocate to each symbol. You can specify either a percentage of portfolio or a fixed amount.
+
+```python
+from investing_algorithm_framework import TradingStrategy, PositionSize, TimeUnit
+
+class MultiAssetStrategy(TradingStrategy):
+    time_unit = TimeUnit.HOUR
+    interval = 2
+    symbols = ["BTC", "ETH", "SOL", "ADA", "XRP"]
+    
+    # Define position sizes for each symbol
+    position_sizes = [
+        PositionSize(symbol="BTC", percentage_of_portfolio=20.0),
+        PositionSize(symbol="ETH", percentage_of_portfolio=20.0),
+        PositionSize(symbol="SOL", percentage_of_portfolio=20.0),
+        PositionSize(symbol="ADA", percentage_of_portfolio=20.0),
+        PositionSize(symbol="XRP", percentage_of_portfolio=20.0),
+    ]
+```
+
+#### Fixed Amount vs Percentage
+
+```python
+# Percentage-based: allocates 20% of total portfolio value
+PositionSize(symbol="BTC", percentage_of_portfolio=20.0)
+
+# Fixed amount: always allocates exactly 500 EUR
+PositionSize(symbol="ETH", fixed_amount=500.0)
+```
+
+#### Proportional Scaling
+
+When multiple buy signals fire simultaneously and the total requested allocation exceeds available funds, the framework **automatically scales all orders proportionally** to ensure fair allocation across all symbols.
+
+**Example:**
+- Portfolio: 1000 EUR available
+- 5 symbols each want 20% = 200 EUR each = 1000 EUR total
+- If only 800 EUR is available, each order is scaled to 160 EUR (80% of requested)
+
+This behavior ensures:
+- **Fair allocation**: All symbols get the same percentage reduction
+- **Predictable results**: Order of symbols doesn't affect allocation
+- **No failures**: Orders are scaled rather than rejected
+
+```python
+# If total allocation exceeds available funds, you'll see a warning:
+# "Total allocation (1000.00) exceeds available funds (800.00). 
+#  Scaling all orders by 80.00% to maintain proportional allocation."
+```
+
+#### Rebalancing Example
+
 ```python
 class PositionSizingStrategy(TradingStrategy):
 

examples/tutorial/notebooks/01_data_exploration.ipynb

@@ -229,6 +229,142 @@
     "                file_path=str(file_path)\n",
     "            )\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11",
+   "metadata": {},
+   "source": [
+    "## Analysis on the Backtest Windows"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from typing import Dict, Tuple\n",
+    "import pandas as pd\n",
+    "from investing_algorithm_framework import create_markdown_table, BacktestDateRange\n",
+    "from IPython.display import Markdown, display\n",
+    "\n",
+    "\n",
+    "def show_backtest_windows_analysis(\n",
+    "    data: Dict[str, Tuple[BacktestDateRange, pd.DataFrame]],\n",
+    "):\n",
+    "    \"\"\"\n",
+    "    Show analysis of backtest windows. Each entry in `data` should map\n",
+    "    a label to a tuple of (date_range, ohlcv_dataframe).\n",
+    "\n",
+    "    Args:\n",
+    "        data (Dict[str, Tuple[BacktestDateRange, pd.DataFrame]]): Mapping\n",
+    "            of labels (backtest window identifiers) to\n",
+    "            (date_range, ohlcv_dataframe)\n",
+    "\n",
+    "    Returns:\n",
+    "        List[Dict]: List of detailed analysis dictionaries for each window\n",
+    "    \"\"\"\n",
+    "    summary_data = []\n",
+    "    detailed_analysis = []\n",
+    "\n",
+    "    for key, (date_range, df) in data.items():\n",
+    "        sliced_data = df[date_range.start_date:date_range.end_date].copy()\n",
+    "\n",
+    "        if sliced_data.empty:\n",
+    "            continue\n",
+    "\n",
+    "        # Calculate comprehensive metrics\n",
+    "        sliced_data['returns'] = sliced_data['Close'].pct_change().dropna()\n",
+    "\n",
+    "        start_price = sliced_data['Close'].iloc[0]\n",
+    "        end_price = sliced_data['Close'].iloc[-1]\n",
+    "        total_return = (end_price / start_price - 1) * 100\n",
+    "\n",
+    "        daily_returns = sliced_data['returns'] * 100\n",
+    "        volatility = daily_returns.std() * np.sqrt(365)\n",
+    "        mean_daily_return = daily_returns.mean()\n",
+    "        sharpe_ratio = (mean_daily_return * 365) / volatility if volatility > 0 else 0\n",
+    "\n",
+    "        # Drawdown analysis\n",
+    "        rolling_max = sliced_data['Close'].cummax()\n",
+    "        drawdown = (sliced_data['Close'] / rolling_max - 1) * 100\n",
+    "        max_drawdown = drawdown.min()\n",
+    "\n",
+    "        # Volatility regimes\n",
+    "        high_vol_days = (daily_returns.abs() > daily_returns.abs().quantile(0.8)).sum()\n",
+    "        low_vol_days = (daily_returns.abs() < daily_returns.abs().quantile(0.2)).sum()\n",
+    "\n",
+    "        # Trend analysis (count of data points, not calendar days)\n",
+    "        up_periods = (daily_returns > 0).sum()\n",
+    "        down_periods = (daily_returns < 0).sum()\n",
+    "        total_periods = len(sliced_data)\n",
+    "\n",
+    "        # Duration in calendar days\n",
+    "        duration_days = (date_range.end_date - date_range.start_date).days\n",
+    "        start_date_str = date_range.start_date.strftime('%Y-%m-%d')\n",
+    "        end_date_str = date_range.end_date.strftime('%Y-%m-%d')\n",
+    "\n",
+    "        summary_data.append({\n",
+    "            \"window\": key,\n",
+    "            \"date_range\": f\"{start_date_str} to {end_date_str}\",\n",
+    "            \"days\": str(duration_days),\n",
+    "            \"avg_daily_return\": f\"{mean_daily_return:.3f}%\",\n",
+    "            \"cumulative_return\": f\"{total_return:.2f}%\",\n",
+    "            \"volatility_ann\": f\"{volatility:.2f}%\",\n",
+    "            \"sharpe_ratio\": f\"{sharpe_ratio:.2f}\",\n",
+    "            \"max_drawdown\": f\"{max_drawdown:.2f}%\",\n",
+    "            \"up_periods\": f\"{up_periods} ({up_periods/total_periods*100:.1f}%)\",\n",
+    "            \"down_periods\": f\"{down_periods} ({down_periods/total_periods*100:.1f}%)\",\n",
+    "            \"high_vol_periods\": f\"{high_vol_days} ({high_vol_days/total_periods*100:.1f}%)\",\n",
+    "            \"low_vol_periods\": f\"{low_vol_days} ({low_vol_days/total_periods*100:.1f}%)\"\n",
+    "        })\n",
+    "\n",
+    "        # Detailed analysis for each period\n",
+    "        detailed_analysis.append({\n",
+    "            'name': key,\n",
+    "            'total_return': total_return,\n",
+    "            'volatility': volatility,\n",
+    "            'sharpe_ratio': sharpe_ratio,\n",
+    "            'max_drawdown': max_drawdown,\n",
+    "            'up_periods': up_periods,\n",
+    "            'down_periods': down_periods,\n",
+    "            'high_vol_periods': high_vol_days,\n",
+    "            'low_vol_periods': low_vol_days,\n",
+    "            'duration_days': duration_days,\n",
+    "            'total_periods': total_periods,\n",
+    "            'mean_daily_return': mean_daily_return,\n",
+    "            'start_price': start_price,\n",
+    "            'end_price': end_price\n",
+    "        })\n",
+    "\n",
+    "    # Create and display the markdown table\n",
+    "    table = create_markdown_table(summary_data)\n",
+    "    display(Markdown(table))\n",
+    "\n",
+    "    return detailed_analysis\n",
+    "\n",
+    "\n",
+    "# Prepare data for analysis - use BTC as reference asset\n",
+    "btc_data = in_sample_data[\"BTC\"][\"2h\"][\"data\"]\n",
+    "\n",
+    "# Create analysis data dictionary from rolling backtest windows\n",
+    "analysis_data = {}\n",
+    "for i, window in enumerate(rolling_backtest_windows):\n",
+    "    train_range = window[\"train_range\"]\n",
+    "    analysis_data[f\"Window {i+1} (Train)\"] = (train_range, btc_data)\n",
+    "\n",
+    "    if \"test_range\" in window:\n",
+    "        test_range = window[\"test_range\"]\n",
+    "        analysis_data[f\"Window {i+1} (Test)\"] = (test_range, btc_data)\n",
+    "\n",
+    "# Show the analysis\n",
+    "detailed_results = show_backtest_windows_analysis(\n",
+    "    data=analysis_data,\n",
+    ")\n"
+   ]
   }
  ],
  "metadata": {

investing_algorithm_framework/__init__.py

@@ -1,6 +1,7 @@
 from .analysis import generate_rolling_backtest_windows, \
     select_backtest_date_ranges, rank_results, create_weights, \
-    get_missing_timeseries_data_entries, fill_missing_timeseries_data
+    get_missing_timeseries_data_entries, fill_missing_timeseries_data, \
+    create_markdown_table
 from .app import App, Algorithm, \
     TradingStrategy, StatelessAction, Task, AppHook, Context, \
     add_html_report, BacktestReport, \
@@ -205,5 +206,6 @@
     "generate_rolling_backtest_windows",
     "tqdm",
     "get_missing_timeseries_data_entries",
-    "fill_missing_timeseries_data"
+    "fill_missing_timeseries_data",
+    "create_markdown_table"
 ]