Skip to content

Martingale42/nautilus-dev / skills/nt-signals

nt-signals

Unverified

Use when working with indicators, signal generation, bar aggregation, custom data types, analysis statistics, or tearsheets in NautilusTrader.

FileKindSize
SKILL.mdskill md7.8 KB
references/api/.gitkeepother0 B
references/api/analysis.mdmarkdown534 B
references/api/book.mdmarkdown160 B
references/api/data.mdmarkdown154 B
references/api/indicators.mdmarkdown1.2 KB
references/api/portfolio.mdmarkdown380 B
references/concepts/.gitkeepother0 B
references/concepts/data.mdmarkdown68.9 KB
references/concepts/portfolio.mdmarkdown6.7 KB
references/concepts/reports.mdmarkdown16.2 KB
references/concepts/visualization.mdmarkdown19.3 KB
references/examples/.gitkeepother0 B
references/examples/bar_aggregation/README.mdmarkdown500 B
references/examples/bar_aggregation/run_example.pyscript3.9 KB
references/examples/bar_aggregation/strategy.pyscript5.1 KB
references/examples/cascaded_indicators/README.mdmarkdown839 B
references/examples/cascaded_indicators/run_example.pyscript4.2 KB
references/examples/cascaded_indicators/strategy.pyscript4.7 KB
references/examples/indicators/README.mdmarkdown632 B
references/examples/indicators/run_example.pyscript3.8 KB
references/examples/indicators/strategy.pyscript5.3 KB
references/guides/.gitkeepother0 B
references/guides/custom_data_patterns.mdmarkdown10.4 KB
references/guides/indicators_guide.mdmarkdown14.6 KB
references/python/analysis/__init__.pyscript5.2 KB
references/python/analysis/analyzer.pyscript16.6 KB
references/python/analysis/config.pyscript6.4 KB
references/python/analysis/reporter.pyscript6.2 KB
references/python/analysis/statistic.pyscript3.8 KB
references/python/analysis/tearsheet.pyscript58.4 KB
references/python/analysis/themes.pyscript6.3 KB
references/rust/analysis/Cargo.tomlmanifest1.1 KB
references/rust/analysis/LICENSEother13 B
references/rust/analysis/README.mdmarkdown2.9 KB
references/rust/analysis/src/analyzer.rsscript31.1 KB
references/rust/analysis/src/lib.rsscript3.2 KB
references/rust/analysis/src/python/analyzer.rsscript13.0 KB
references/rust/analysis/src/python/mod.rsscript2.7 KB
references/rust/analysis/src/python/statistics/cagr.rsscript1.6 KB
references/rust/analysis/src/python/statistics/calmar_ratio.rsscript1.6 KB
references/rust/analysis/src/python/statistics/expectancy.rsscript1.9 KB
references/rust/analysis/src/python/statistics/long_ratio.rsscript2.7 KB
references/rust/analysis/src/python/statistics/loser_avg.rsscript1.9 KB
references/rust/analysis/src/python/statistics/loser_max.rsscript1.9 KB
references/rust/analysis/src/python/statistics/loser_min.rsscript1.9 KB
references/rust/analysis/src/python/statistics/max_drawdown.rsscript1.5 KB
references/rust/analysis/src/python/statistics/mod.rsscript1.6 KB
references/rust/analysis/src/python/statistics/profit_factor.rsscript1.8 KB
references/rust/analysis/src/python/statistics/returns_avg.rsscript1.8 KB
references/rust/analysis/src/python/statistics/returns_avg_loss.rsscript1.8 KB
references/rust/analysis/src/python/statistics/returns_avg_win.rsscript1.8 KB
references/rust/analysis/src/python/statistics/returns_volatility.rsscript1.9 KB
references/rust/analysis/src/python/statistics/risk_return_ratio.rsscript1.8 KB
references/rust/analysis/src/python/statistics/sharpe_ratio.rsscript1.9 KB
references/rust/analysis/src/python/statistics/sortino_ratio.rsscript1.9 KB
references/rust/analysis/src/python/statistics/win_rate.rsscript1.9 KB
references/rust/analysis/src/python/statistics/winner_avg.rsscript1.9 KB
references/rust/analysis/src/python/statistics/winner_max.rsscript1.9 KB
references/rust/analysis/src/python/statistics/winner_min.rsscript1.9 KB
references/rust/analysis/src/statistic.rsscript4.1 KB
references/rust/analysis/src/statistics/cagr.rsscript7.0 KB
references/rust/analysis/src/statistics/calmar_ratio.rsscript5.5 KB
references/rust/analysis/src/statistics/expectancy.rsscript6.8 KB
references/rust/analysis/src/statistics/long_ratio.rsscript8.0 KB
references/rust/analysis/src/statistics/loser_avg.rsscript4.1 KB
references/rust/analysis/src/statistics/loser_max.rsscript4.1 KB
references/rust/analysis/src/statistics/loser_min.rsscript4.2 KB
references/rust/analysis/src/statistics/max_drawdown.rsscript4.8 KB
references/rust/analysis/src/statistics/mod.rsscript1.3 KB
references/rust/analysis/src/statistics/profit_factor.rsscript5.8 KB
references/rust/analysis/src/statistics/returns_avg.rsscript3.9 KB
references/rust/analysis/src/statistics/returns_avg_loss.rsscript4.5 KB
references/rust/analysis/src/statistics/returns_avg_win.rsscript4.0 KB
references/rust/analysis/src/statistics/returns_volatility.rsscript4.9 KB
references/rust/analysis/src/statistics/risk_return_ratio.rsscript4.3 KB
references/rust/analysis/src/statistics/sharpe_ratio.rsscript4.8 KB
references/rust/analysis/src/statistics/sortino_ratio.rsscript5.1 KB
references/rust/analysis/src/statistics/win_rate.rsscript4.1 KB
references/rust/analysis/src/statistics/winner_avg.rsscript3.6 KB
references/rust/analysis/src/statistics/winner_max.rsscript3.6 KB
references/rust/analysis/src/statistics/winner_min.rsscript4.0 KB
templates/.gitkeepother0 B
templates/custom_data.pyscript2.0 KB
templates/indicator.pyscript2.6 KB
templates/portfolio_statistic.pyscript2.3 KB

references/concepts/reports.md

View on GitHub
# Reports

This guide explains the portfolio analysis and reporting capabilities provided by the `ReportProvider`
class, and how these reports are used for PnL accounting and backtest post-run analysis.

## Overview

The `ReportProvider` class in NautilusTrader generates structured analytical reports from
trading data, transforming raw orders, fills, positions, and account states into pandas DataFrames
for analysis and visualization. These reports are essential for understanding strategy performance,
analyzing execution quality, and ensuring accurate PnL accounting.

Reports can be generated using two approaches:

- **Trader helper methods** (recommended): Convenient methods like `trader.generate_orders_report()`.
- **ReportProvider directly**: For more control over data selection and filtering.

Reports provide consistent analytics across both backtesting and live trading environments,
enabling reliable performance evaluation and strategy comparison.

## Available reports

The `ReportProvider` class offers several static methods to generate reports from trading data.
Each report returns a pandas DataFrame with specific columns and indexing for easy analysis.

### Orders report

Generates a full view of all orders:

```python
# Using Trader helper method (recommended)
orders_report = trader.generate_orders_report()

# Or using ReportProvider directly
from nautilus_trader.analysis import ReportProvider

orders = cache.orders()
orders_report = ReportProvider.generate_orders_report(orders)
```

**Returns `pd.DataFrame`. Key columns include:**

| Column             | Description                                             |
|--------------------|---------------------------------------------------------|
| `client_order_id`  | Index - unique order identifier.                        |
| `instrument_id`    | Trading instrument.                                     |
| `strategy_id`      | Strategy that created the order.                        |
| `trader_id`        | Trader identifier.                                      |
| `account_id`       | Account identifier (if assigned).                       |
| `venue_order_id`   | Venue-assigned order ID (if accepted).                  |
| `side`             | BUY or SELL.                                            |
| `type`             | MARKET, LIMIT, etc.                                     |
| `status`           | Current order status.                                   |
| `quantity`         | Original order quantity (string).                       |
| `filled_qty`       | Amount filled (string).                                 |
| `price`            | Limit price (order-type dependent).                     |
| `avg_px`           | Average fill price (if filled).                         |
| `time_in_force`    | Time-in-force instruction.                              |
| `ts_init`          | Order initialization timestamp (Unix nanoseconds).      |
| `ts_last`          | Last update timestamp (Unix nanoseconds).               |

Additional columns vary by order type (e.g., `trigger_price` for stop orders, `expire_time` for
GTD orders). See `Order.to_dict()` for the complete field list.

### Order fills report

Provides a summary of filled orders (one row per order):

```python
# Using Trader helper method (recommended)
fills_report = trader.generate_order_fills_report()

# Or using ReportProvider directly
orders = cache.orders()
fills_report = ReportProvider.generate_order_fills_report(orders)
```

This report includes only orders with `filled_qty > 0` and contains the same columns as the
orders report, but filtered to executed orders only. Note that `ts_init` and `ts_last` are
converted to datetime objects in this report for easier analysis.

### Fills report

Details individual fill events (one row per fill):

```python
# Using Trader helper method (recommended)
fills_report = trader.generate_fills_report()

# Or using ReportProvider directly
orders = cache.orders()
fills_report = ReportProvider.generate_fills_report(orders)
```

**Returns `pd.DataFrame`. Key columns include:**

| Column             | Description                              |
|--------------------|------------------------------------------|
| `client_order_id`  | Index - order identifier.                |
| `trade_id`         | Unique trade/fill identifier.            |
| `venue_order_id`   | Venue-assigned order ID.                 |
| `instrument_id`    | Trading instrument.                      |
| `strategy_id`      | Strategy that created the order.         |
| `account_id`       | Account identifier.                      |
| `position_id`      | Associated position ID (if applicable).  |
| `order_side`       | BUY or SELL.                             |
| `order_type`       | Order type (MARKET, LIMIT, etc.).        |
| `last_px`          | Fill execution price (string).           |
| `last_qty`         | Fill execution quantity (string).        |
| `currency`         | Currency of the fill.                    |
| `liquidity_side`   | MAKER or TAKER.                          |
| `commission`       | Commission amount and currency.          |
| `ts_event`         | Fill timestamp (datetime).               |
| `ts_init`          | Initialization timestamp (datetime).     |

See `OrderFilled.to_dict()` for the complete field list.

### Positions report

Position analysis including snapshots:

```python
# Using Trader helper method (recommended)
# Automatically includes snapshots for NETTING OMS
positions_report = trader.generate_positions_report()

# Or using ReportProvider directly
positions = cache.positions()
snapshots = cache.position_snapshots()  # For NETTING OMS
positions_report = ReportProvider.generate_positions_report(
    positions=positions,
    snapshots=snapshots
)
```

**Returns `pd.DataFrame`. Key columns include:**

| Column             | Description                              |
|--------------------|------------------------------------------|
| `position_id`      | Index - unique position identifier.      |
| `instrument_id`    | Trading instrument.                      |
| `strategy_id`      | Strategy that managed the position.      |
| `trader_id`        | Trader identifier.                       |
| `account_id`       | Account identifier.                      |
| `opening_order_id` | Order ID that opened the position.       |
| `closing_order_id` | Order ID that closed the position.       |
| `entry`            | Entry side (BUY or SELL).                |
| `side`             | Position side (LONG, SHORT, or FLAT).    |
| `quantity`         | Current position size.                   |
| `peak_qty`         | Maximum size reached.                    |
| `avg_px_open`      | Average entry price.                     |
| `avg_px_close`     | Average exit price (if closed).          |
| `commissions`      | List of commissions paid.                |
| `realized_pnl`     | Realized profit/loss.                    |
| `realized_return`  | Return percentage.                       |
| `ts_init`          | Position initialization timestamp.       |
| `ts_opened`        | Opening timestamp (datetime).            |
| `ts_last`          | Last update timestamp.                   |
| `ts_closed`        | Closing timestamp (datetime or NA).      |
| `duration_ns`      | Position duration in nanoseconds.        |
| `is_snapshot`      | Whether this is a historical snapshot.   |

### Account report

Tracks account balance and margin changes over time:

```python
# Using Trader helper method (recommended)
# Requires venue parameter
from nautilus_trader.model.identifiers import Venue
venue = Venue("BINANCE")
account_report = trader.generate_account_report(venue)

# Or using ReportProvider directly
account = cache.account(account_id)
account_report = ReportProvider.generate_account_report(account)
```

**Returns `pd.DataFrame`. Columns include:**

| Column          | Description                                |
|-----------------|--------------------------------------------|
| `ts_event`      | Index - timestamp of account state change. |
| `account_id`    | Account identifier.                        |
| `account_type`  | Type of account (e.g., SPOT, MARGIN).      |
| `base_currency` | Base currency for the account.             |
| `total`         | Total balance amount (string).             |
| `free`          | Available balance (string).                |
| `locked`        | Balance locked in orders (string).         |
| `currency`      | Currency of the balance.                   |
| `reported`      | Whether balance was reported by venue.     |
| `margins`       | Margin information (list, if applicable).  |
| `info`          | Additional venue-specific information.     |

Each row represents a balance entry; accounts with multiple currencies produce multiple rows
per account state event.

## PnL accounting considerations

Accurate PnL accounting requires careful consideration of several factors:

### Position-based PnL

- **Realized PnL**: Calculated when positions are partially or fully closed.
- **Unrealized PnL**: Marked-to-market using current prices.
- **Commission impact**: Only included when in settlement currency.

:::warning
PnL calculations depend on the OMS type. In `NETTING` OMS, position snapshots
preserve historical PnL when positions reopen. Always include snapshots in
reports for accurate total PnL calculation. In `HEDGING` OMS, snapshots are
not used since each position has a unique ID and is never reopened.
:::

### Multi-currency accounting

When dealing with multiple currencies:

- Each position tracks PnL in its settlement currency.
- Portfolio aggregation requires currency conversion.
- Commission currencies may differ from settlement currency.

```python
# Accessing PnL across positions
for position in positions:
    realized = position.realized_pnl  # In settlement currency
    unrealized = position.unrealized_pnl(last_price)

    # Handle multi-currency aggregation (illustrative)
    # Note: Currency conversion requires user-provided exchange rates
    if position.settlement_currency != base_currency:
        # Apply conversion rate from your data source
        # rate = get_exchange_rate(position.settlement_currency, base_currency)
        # realized_converted = realized.as_double() * rate
        pass
```

### Snapshot considerations

For `NETTING` OMS:

```python
from nautilus_trader.model.objects import Money

# Include snapshots for complete PnL (per currency)
pnl_by_currency = {}

# Add PnL from current positions
for position in cache.positions(instrument_id=instrument_id):
    if position.realized_pnl:
        currency = position.realized_pnl.currency
        if currency not in pnl_by_currency:
            pnl_by_currency[currency] = 0.0
        pnl_by_currency[currency] += position.realized_pnl.as_double()

# Add PnL from historical snapshots
for snapshot in cache.position_snapshots(instrument_id=instrument_id):
    if snapshot.realized_pnl:
        currency = snapshot.realized_pnl.currency
        if currency not in pnl_by_currency:
            pnl_by_currency[currency] = 0.0
        pnl_by_currency[currency] += snapshot.realized_pnl.as_double()

# Create Money objects for each currency
total_pnls = [Money(amount, currency) for currency, amount in pnl_by_currency.items()]
```

## Backtest post-run analysis

After a backtest completes, analysis is available through various reports
and the portfolio analyzer.

### Accessing backtest results

```python
# After backtest run
engine.run(start=start_time, end=end_time)

# Generate reports using Trader helper methods
orders_report = engine.trader.generate_orders_report()
positions_report = engine.trader.generate_positions_report()
fills_report = engine.trader.generate_fills_report()

# Or access data directly for custom analysis
orders = engine.cache.orders()
positions = engine.cache.positions()
snapshots = engine.cache.position_snapshots()
```

### Portfolio statistics

The portfolio analyzer provides performance metrics:

```python
# Access portfolio analyzer
portfolio = engine.portfolio

# Get different categories of statistics
stats_pnls = portfolio.analyzer.get_performance_stats_pnls()
stats_returns = portfolio.analyzer.get_performance_stats_returns()
stats_general = portfolio.analyzer.get_performance_stats_general()
```

:::info
For detailed information about available statistics and creating custom metrics,
see the [Portfolio guide](portfolio.md#portfolio-statistics). The Portfolio guide covers:

- Built-in statistics categories (PnLs, returns, positions, orders based).
- Creating custom statistics with `PortfolioStatistic`.
- Registering and using custom metrics.

:::

### Visualization

NautilusTrader provides interactive tearsheets and plots via Plotly:

```python
from nautilus_trader.analysis import create_tearsheet

# After backtest run
engine.run()

# Generate interactive HTML tearsheet
create_tearsheet(engine, output_path="tearsheet.html")
```

This creates an interactive HTML report with:

- Equity curve
- Drawdown analysis
- Monthly returns heatmap
- Performance statistics table
- Returns distribution

For more control, generate individual plots:

```python
from nautilus_trader.analysis import create_equity_curve

returns = engine.portfolio.analyzer.returns()
fig = create_equity_curve(returns, title="My Strategy Equity")
fig.show()  # Display in browser
fig.write_image("equity.png")  # Export to PNG (requires kaleido)
```

Install visualization dependencies:

```bash
uv pip install "nautilus_trader[visualization]"
```

## Report generation patterns

### Live trading

During live trading, generate reports periodically:

```python
import pandas as pd

class ReportingActor(Actor):
    def on_start(self):
        # Schedule periodic reporting
        self.clock.set_timer(
            name="generate_reports",
            interval=pd.Timedelta(minutes=30),
            callback=self.generate_reports
        )

    def generate_reports(self, event):
        # Generate and log reports
        positions_report = self.trader.generate_positions_report()

        # Save or transmit report
        positions_report.to_csv(f"positions_{event.ts_event}.csv")
```

### Performance analysis

For backtest analysis:

```python
import pandas as pd

# Run the backtest
engine.run(start=start_time, end=end_time)

# Collect results
positions_closed = engine.cache.positions_closed()
stats_pnls = engine.portfolio.analyzer.get_performance_stats_pnls()
stats_returns = engine.portfolio.analyzer.get_performance_stats_returns()
stats_general = engine.portfolio.analyzer.get_performance_stats_general()

# Create summary dictionary
results = {
    "total_positions": len(positions_closed),
    "pnl_total": stats_pnls.get("PnL (total)"),
    "sharpe_ratio": stats_returns.get("Sharpe Ratio (252 days)"),
    "profit_factor": stats_general.get("Profit Factor"),
    "win_rate": stats_general.get("Win Rate"),
}

# Display results
results_df = pd.DataFrame([results])
print(results_df.T)  # Transpose for vertical display
```

:::info
Reports are generated from in-memory data structures. For large-scale analysis
or long-running systems, consider persisting reports to a database for efficient
querying. See the [Cache guide](cache.md) for persistence options.
:::

## Integration with other components

The `ReportProvider` works with several system components:

- **Cache**: Source of all trading data (orders, positions, accounts) for reports.
- **Portfolio**: Uses reports for performance analysis and metrics calculation.
- **BacktestEngine**: Uses reports for post-run analysis and visualization.
- **Position snapshots**: Required for accurate PnL reporting in `NETTING` OMS.

## Summary

The `ReportProvider` class offers a suite of analytical reports for evaluating
trading performance. These reports transform raw trading data into structured DataFrames,
enabling detailed analysis of orders, fills, positions, and account states. Understanding
how to generate and interpret these reports is essential for strategy development,
performance evaluation, and accurate PnL accounting, particularly when dealing with
position snapshots in `NETTING` OMS.

## Related guides

- [Visualization](visualization.md) - Learn how to create interactive tearsheets and charts from backtest results.
- [Portfolio](portfolio.md) - Explore portfolio statistics and performance metrics.
- [Backtesting](backtesting.md) - Learn how to run backtests that generate reports.
- [Cache](cache.md) - Understand the cache system that stores data for reports.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall