feat: rename equity_path to trade_path and fix strategy statistics

Breaking changes:
- Rename equity_path parameter to trade_path in ScriptRunner and CLI
- Change CLI flags from --equity/-ep to --trade/-tp
- Update default filename from _equity.csv to _trade.csv
- Fix strategy statistics CSV export with proper headers and numeric values
- Add comprehensive TradingView-compatible statistics calculation
- Version bump to 6.1.0 for breaking API changes

Author: wallneradam

docs/cli/run.md

@@ -5,7 +5,7 @@ title: "Running Scripts"
 description: "Running PyneCore scripts from the command line"
 icon: "play_circle"
 date: "2025-03-31"
-lastmod: "2025-03-31"
+lastmod: "2025-07-24"
 draft: false
 toc: true
 categories: ["Usage", "CLI", "Scripting"]
@@ -73,12 +73,12 @@ pyne run my_strategy.py eurusd_data.ohlcv --from "2023-01-01" --to "2023-12-31"
 
 - `--plot`, `-pp`: Path to save the plot data (CSV format). If not specified, it will be saved as `<script_name>.csv` in the `workdir/output/` directory.
 - `--strat`, `-sp`: Path to save the strategy statistics (CSV format). If not specified, it will be saved as `<script_name>_strat.csv` in the `workdir/output/` directory.
-- `--equity`, `-ep`: Path to save the equity curve (CSV format). If not specified, it will be saved as `<script_name>_equity.csv` in the `workdir/output/` directory.
+- `--trade`, `-tp`: Path to save the trade data (CSV format). If not specified, it will be saved as `<script_name>_trade.csv` in the `workdir/output/` directory.
 
 Example:
 ```bash
 # Specify custom output paths
-pyne run my_strategy.py eurusd_data.ohlcv --plot custom_plot.csv --strat custom_stats.csv
+pyne run my_strategy.py eurusd_data.ohlcv --plot custom_plot.csv --strat custom_stats.csv --trade custom_trades.csv
 ```
 
 ## Symbol Information
@@ -120,18 +120,34 @@ After the script execution completes, several output files are created:
 
 Contains the values plotted by the script for each bar. This includes all values passed to `plot()` functions in your script.
 
+**Default filename**: `<script_name>.csv`
+
 ### Strategy Statistics (CSV)
 
-If your script is a strategy, this file contains detailed statistics about the trading performance, including:
-- Total profit/loss
-- Win rate
-- Maximum drawdown
-- Sharpe ratio
-- Trade details
+If your script is a strategy, this file contains comprehensive TradingView-compatible statistics about the trading performance, including:
+- **Overview metrics**: Net profit, gross profit/loss, max equity runup/drawdown, buy & hold return
+- **Performance ratios**: Sharpe ratio, Sortino ratio, profit factor
+- **Trade statistics**: Total/winning/losing trades, percent profitable, average trade metrics
+- **Position analysis**: Largest winning/losing trades, average bars in trades
+- **Long/Short breakdown**: Separate statistics for long and short positions
+- **Risk metrics**: Max contracts held, commission paid, margin calls
+
+**Default filename**: `<script_name>_strat.csv`
+
+### Trade Data (CSV)
+
+If your script is a strategy, this file contains detailed trade-by-trade data with entry and exit records:
+- **Trade information**: Trade number, bar index, entry/exit type, signal ID
+- **Timing data**: Date/time of entry and exit
+- **Price data**: Entry/exit prices in the symbol's currency
+- **Position data**: Number of contracts traded
+- **Performance metrics**: Profit/loss in currency and percentage
+- **Cumulative tracking**: Running totals of profit and profit percentage
+- **Risk analysis**: Maximum run-up and drawdown for each trade
 
-### Equity Curve (CSV)
+**Default filename**: `<script_name>_trade.csv`
 
-If your script is a strategy, this file contains the equity curve data showing how the account balance changed over time.
+**Note**: This file exports individual trade records (entry/exit pairs), not the equity curve. The equity curve is tracked internally for statistics calculation.
 
 ## Examples
 
@@ -156,7 +172,7 @@ pyne run my_strategy.py eurusd_data.ohlcv --from "2023-03-01" --to "2023-03-31"
 pyne run my_strategy.py eurusd_data.ohlcv \
   --plot ./analysis/my_plot.csv \
   --strat ./analysis/my_stats.csv \
-  --equity ./analysis/my_equity.csv
+  --trade ./analysis/my_trades.csv
 ```
 
 ## Troubleshooting

pyproject.toml

@@ -16,7 +16,7 @@ egg_info.egg_base = "build"
 
 [project]
 name = "pynesys-pynecore"
-version = "6.0.18" # PineVersion.Major.Minor
+version = "6.1.0" # PineVersion.Major.Minor
 description = "Python based Pine Script like runtime and API"
 authors = [{ name = "PYNESYS LLC", email = "hello@pynesys.com" }]
 readme = "README.md"

src/pynecore/cli/commands/run.py

@@ -71,9 +71,9 @@ def run(
                                          help="Path to save the strategy statistics",
                                          rich_help_panel="Out Path Options"
                                          ),
-        equity_path: Path | None = Option(None, "--equity", "-ep",
-                                          help="Path to save the equity curve",
-                                          rich_help_panel="Out Path Options"),
+        trade_path: Path | None = Option(None, "--trade", "-tp",
+                                         help="Path to save the trade data",
+                                         rich_help_panel="Out Path Options"),
 ):
     """
     Run a script
@@ -83,7 +83,7 @@ def run(
 
     If [bold]script[/] path is a name without full path, it will be searched in the [italic]"workdir/scripts"[/] directory.
     Similarly, if [bold]data[/] path is a name without full path, it will be searched in the [italic]"workdir/data"[/] directory.
-    The [bold]plot_path[/], [bold]strat_path[/], and [bold]equity_path[/] work the same way - if they are names without full paths,
+    The [bold]plot_path[/], [bold]strat_path[/], and [bold]trade_path[/] work the same way - if they are names without full paths,
     they will be saved in the [italic]"workdir/output"[/] directory.
     """  # noqa
     # Ensure .py extension
@@ -132,11 +132,11 @@ def run(
     if not strat_path:
         strat_path = app_state.output_dir / f"{script.stem}_strat.csv"
 
-    # Ensure .csv extension for equity path
-    if equity_path and equity_path.suffix != ".csv":
-        equity_path = equity_path.with_suffix(".csv")
-    if not equity_path:
-        equity_path = app_state.output_dir / f"{script.stem}_equity.csv"
+    # Ensure .csv extension for trade path
+    if trade_path and trade_path.suffix != ".csv":
+        trade_path = trade_path.with_suffix(".csv")
+    if not trade_path:
+        trade_path = app_state.output_dir / f"{script.stem}_trade.csv"
 
     # Get symbol info for the data
     try:
@@ -177,7 +177,7 @@ def run(
             try:
                 # Create script runner (this is where the import happens)
                 runner = ScriptRunner(script, ohlcv_iter, syminfo, last_bar_index=size - 1,
-                                      plot_path=plot_path, strat_path=strat_path, equity_path=equity_path)
+                                      plot_path=plot_path, strat_path=strat_path, trade_path=trade_path)
             finally:
                 # Remove lib directory from Python path
                 if lib_path_added:

src/pynecore/core/script_runner.py

@@ -7,6 +7,7 @@
 from pynecore.types.ohlcv import OHLCV
 from pynecore.core.syminfo import SymInfo
 from pynecore.core.csv_file import CSVWriter
+from pynecore.core.strategy_stats import calculate_strategy_statistics, write_strategy_statistics_csv
 
 from pynecore.types import script_type
 
@@ -145,11 +146,12 @@ class ScriptRunner:
     """
 
     __slots__ = ('script_module', 'script', 'ohlcv_iter', 'syminfo', 'update_syminfo_every_run',
-                 'bar_index', 'tz', 'plot_writer', 'strat_writer', 'equity_writer', 'last_bar_index')
+                 'bar_index', 'tz', 'plot_writer', 'strat_writer', 'trades_writer', 'last_bar_index',
+                 'equity_curve', 'first_price', 'last_price')
 
     def __init__(self, script_path: Path, ohlcv_iter: Iterable[OHLCV], syminfo: SymInfo, *,
                  plot_path: Path | None = None, strat_path: Path | None = None,
-                 equity_path: Path | None = None,
+                 trade_path: Path | None = None,
                  update_syminfo_every_run: bool = False, last_bar_index=0):
         """
         Initialize the script runner
@@ -159,7 +161,7 @@ def __init__(self, script_path: Path, ohlcv_iter: Iterable[OHLCV], syminfo: SymI
         :param syminfo: Symbol information
         :param plot_path: Path to save the plot data
         :param strat_path: Path to save the strategy results
-        :param equity_path: Path to save the equity data of the strategy
+        :param trade_path: Path to save the trade data of the strategy
         :param update_syminfo_every_run: If it is needed to update the syminfo lib in every run,
                                          needed for parallel script executions
         :param last_bar_index: Last bar index, the index of the last bar of the historical data
@@ -186,16 +188,26 @@ def __init__(self, script_path: Path, ohlcv_iter: Iterable[OHLCV], syminfo: SymI
 
         self.tz = _parse_timezone(syminfo.timezone)
 
+        # Initialize tracking variables for statistics
+        self.equity_curve: list[float] = []
+        self.first_price: float | None = None
+        self.last_price: float | None = None
+
         self.plot_writer = CSVWriter(
             plot_path, float_fmt=f".8g"
         ) if plot_path else None
-        self.strat_writer = CSVWriter(strat_path) if strat_path else None
-        self.equity_writer = CSVWriter(equity_path, headers=(
+        self.strat_writer = CSVWriter(strat_path, headers=(
+            "Metric",
+            f"All {syminfo.currency}", "All %",
+            f"Long {syminfo.currency}", "Long %",
+            f"Short {syminfo.currency}", "Short %",
+        )) if strat_path else None
+        self.trades_writer = CSVWriter(trade_path, headers=(
             "Trade #", "Bar Index", "Type", "Signal", "Date/Time", f"Price {syminfo.currency}",
             "Contracts", f"Profit {syminfo.currency}", "Profit %", f"Cumulative profit {syminfo.currency}",
             "Cumulative profit %", f"Run-up {syminfo.currency}", "Run-up %", f"Drawdown {syminfo.currency}",
             "Drawdown %",
-        )) if equity_path else None
+        )) if trade_path else None
 
     # noinspection PyProtectedMember
     def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
@@ -233,9 +245,9 @@ def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
 
         # If the script is a strategy, we open strategy output files too
         if is_strat:
-            # Open equity writer if we have one
-            if self.equity_writer:
-                self.equity_writer.open()
+            # Open trade writer if we have one
+            if self.trades_writer:
+                self.trades_writer.open()
 
         # Clear plot data
         lib._plot_data.clear()
@@ -259,6 +271,13 @@ def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
                 # Update lib properties
                 _set_lib_properties(candle, self.bar_index, self.tz, lib)
 
+                # Store first price for buy & hold calculation
+                if self.first_price is None:
+                    self.first_price = lib.close  # type: ignore
+
+                # Update last price
+                self.last_price = lib.close  # type: ignore
+
                 # Reset function increments
                 function_isolation.reset_step()
 
@@ -295,11 +314,11 @@ def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
                 elif position:
                     yield candle, lib._plot_data, position.new_closed_trades
 
-                # Save equity data if we have a writer
-                if is_strat and self.equity_writer and position:
+                # Save trade data if we have a writer
+                if is_strat and self.trades_writer and position:
                     for trade in position.new_closed_trades:
                         trade_num += 1  # Start from 1
-                        self.equity_writer.write(
+                        self.trades_writer.write(
                             trade_num,
                             trade.entry_bar_index,
                             "Entry long" if trade.size > 0 else "Entry short",
@@ -316,7 +335,7 @@ def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
                             trade.max_drawdown,
                             f"{trade.max_drawdown_percent:.2f}",
                         )
-                        self.equity_writer.write(
+                        self.trades_writer.write(
                             trade_num,
                             trade.exit_bar_index,
                             "Exit long" if trade.size > 0 else "Exit short",
@@ -337,6 +356,11 @@ def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
                 # Clear plot data
                 lib._plot_data.clear()
 
+                # Track equity curve for strategies
+                if is_strat and position:
+                    current_equity = float(position.equity) if position.equity else self.script.initial_capital
+                    self.equity_curve.append(current_equity)
+
                 # Call the progress callback
                 if on_progress and lib._datetime is not None:
                     on_progress(lib._datetime.replace(tzinfo=None))
@@ -352,35 +376,58 @@ def run_iter(self, on_progress: Callable[[datetime], None] | None = None) \
         except GeneratorExit:
             pass
         finally:  # Python reference counter will close this even if the iterator is not exhausted
-            # Export remaining open trades before closing
-            if is_strat and self.equity_writer and position and position.open_trades:
-                for trade in position.open_trades:
-                    trade_num += 1  # Continue numbering from closed trades
-                    # Export only the entry part for open trades
-                    self.equity_writer.write(
-                        trade_num,
-                        trade.entry_bar_index,
-                        "Entry long" if trade.size > 0 else "Entry short",
-                        trade.entry_id,
-                        string.format_time(trade.entry_time),  # type: ignore
-                        trade.entry_price,
-                        abs(trade.size),
-                        0.0,  # No profit yet for open trades
-                        "0.00",  # No profit percent yet
-                        0.0,  # No cumulative profit change
-                        "0.00",  # No cumulative profit percent change
-                        0.0,  # No max runup yet
-                        "0.00",  # No max runup percent yet
-                        0.0,  # No max drawdown yet
-                        "0.00",  # No max drawdown percent yet
-                    )
+            if is_strat and position:
+                # Export remaining open trades before closing
+                if self.trades_writer and position.open_trades:
+                    for trade in position.open_trades:
+                        trade_num += 1  # Continue numbering from closed trades
+                        # Export only the entry part for open trades
+                        self.trades_writer.write(
+                            trade_num,
+                            trade.entry_bar_index,
+                            "Entry long" if trade.size > 0 else "Entry short",
+                            trade.entry_id,
+                            string.format_time(trade.entry_time),  # type: ignore
+                            trade.entry_price,
+                            abs(trade.size),
+                            0.0,  # No profit yet for open trades
+                            "0.00",  # No profit percent yet
+                            0.0,  # No cumulative profit change
+                            "0.00",  # No cumulative profit percent change
+                            0.0,  # No max runup yet
+                            "0.00",  # No max runup percent yet
+                            0.0,  # No max drawdown yet
+                            "0.00",  # No max drawdown percent yet
+                        )
+
+                # Write strategy statistics
+                if self.strat_writer and position:
+                    try:
+                        # Open strat writer and write statistics
+                        self.strat_writer.open()
+
+                        # Calculate comprehensive statistics
+                        stats = calculate_strategy_statistics(
+                            position,
+                            self.script.initial_capital,
+                            self.equity_curve if self.equity_curve else None,
+                            self.first_price,
+                            self.last_price
+                        )
+
+                        write_strategy_statistics_csv(stats, self.strat_writer)
+                        self.strat_writer.close()
+
+                    finally:
+                        # Close strat writer
+                        self.strat_writer.close()
 
             # Close the plot writer
             if self.plot_writer:
                 self.plot_writer.close()
-            # Close the equity writer
-            if self.equity_writer:
-                self.equity_writer.close()
+            # Close the trade writer
+            if self.trades_writer:
+                self.trades_writer.close()
 
             # Reset library variables
             _reset_lib_vars(lib)