Struct Signal 

#[non_exhaustive]
pub struct Signal {

    pub direction: SignalDirection,
    pub strength: SignalStrength,
    pub timestamp: i64,
    pub price: f64,
    pub reason: Option<String>,
    pub metadata: Option<SignalMetadata>,
    pub tags: Vec<String>,
    pub scale_fraction: Option<f64>,
    pub order_type: OrderType,
    pub expires_in_bars: Option<usize>,
    pub bracket_stop_loss_pct: Option<f64>,
    pub bracket_take_profit_pct: Option<f64>,
    pub bracket_trailing_stop_pct: Option<f64>,
}

A trading signal generated by a strategy

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

direction: SignalDirection

Signal direction

strength: SignalStrength

Signal strength/confidence

timestamp: i64

Timestamp when signal was generated

price: f64

Price at signal generation

reason: Option<String>

Optional reason/description

metadata: Option<SignalMetadata>

Strategy-specific metadata (indicator values, etc.)

tags: Vec<String>

User-defined tags for post-hoc trade subgroup analysis.

Tags are propagated to [Trade::tags] when a position closes, enabling BacktestResult::trades_by_tag and metrics_by_tag queries. Use the .tag() builder to attach tags at signal creation time.

scale_fraction: Option<f64>

Fraction for SignalDirection::ScaleIn and SignalDirection::ScaleOut signals.

• ScaleIn: fraction of current portfolio equity to add to the position (0.0..=1.0).
• ScaleOut: fraction of current position quantity to close (0.0..=1.0).

None for all other signal directions. Set via Signal::scale_in / Signal::scale_out constructors.

order_type: OrderType

Order type controlling how this signal’s entry is executed.

OrderType::Market (default) fills at next bar’s open. Limit and stop types queue the order as a PendingOrder and fill when the bar’s high/low reaches the specified price level.

Only meaningful for SignalDirection::Long and SignalDirection::Short signals; ignored for Exit / ScaleIn / ScaleOut / Hold.

expires_in_bars: Option<usize>

Expiry for pending limit/stop orders, measured in bars.

When set, the pending order is cancelled if not filled within this many bars after it is placed. None means Good-Till-Cancelled.

Only relevant when Signal::order_type is not OrderType::Market.

bracket_stop_loss_pct: Option<f64>

Per-trade stop-loss percentage override (0.0 – 1.0).

When set on an entry signal (SignalDirection::Long or SignalDirection::Short), this value is stored on the resulting Position and takes precedence over BacktestConfig::stop_loss_pct for the lifetime of that position.

Set via the .stop_loss(pct) builder method.

bracket_take_profit_pct: Option<f64>

Per-trade take-profit percentage override (0.0 – 1.0).

When set on an entry signal, stored on the resulting Position and takes precedence over BacktestConfig::take_profit_pct.

Set via the .take_profit(pct) builder method.

bracket_trailing_stop_pct: Option<f64>

Per-trade trailing stop percentage override (0.0 – 1.0).

When set on an entry signal, stored on the resulting Position and takes precedence over BacktestConfig::trailing_stop_pct.

Set via the .trailing_stop(pct) builder method.

Implementations

impl Signal

pub fn long(timestamp: i64, price: f64) -> Self

Create a long signal

pub fn short(timestamp: i64, price: f64) -> Self

Create a short signal

pub fn exit(timestamp: i64, price: f64) -> Self

Create an exit signal

pub fn hold() -> Self

Create a hold signal (no action)

pub fn is_hold(&self) -> bool

Check if this is a hold signal

pub fn is_entry(&self) -> bool

Check if this is an entry signal (Long or Short)

pub fn is_exit(&self) -> bool

Check if this is an exit signal

pub fn is_scaling(&self) -> bool

Check if this is a scaling signal (scale-in or scale-out)

pub fn scale_in(fraction: f64, timestamp: i64, price: f64) -> Self

Create a scale-in signal — add to an existing position.

fraction is the portion of current portfolio equity to allocate to the additional shares. Must be in 0.0..=1.0; values outside this range are clamped by the engine. Has no effect if no position is currently open.

Example

use finance_query::backtesting::Signal;

// In a custom Strategy::on_candle implementation:
// Add 10% of current equity to the existing long position.
let signal = Signal::scale_in(0.10, ctx_timestamp, ctx_price);

pub fn scale_out(fraction: f64, timestamp: i64, price: f64) -> Self

Create a scale-out signal — partially exit an existing position.

fraction is the portion of the current position quantity to close. Must be in 0.0..=1.0; values outside this range are clamped. A fraction of 1.0 closes the entire position (equivalent to Signal::exit). Has no effect if no position is currently open.

Example

use finance_query::backtesting::Signal;

// In a custom Strategy::on_candle implementation:
// Close half the current position to lock in partial profits.
let signal = Signal::scale_out(0.50, ctx_timestamp, ctx_price);

pub fn buy_limit(timestamp: i64, price: f64, limit_price: f64) -> Self

Create a limit buy order — enter long when price pulls back to limit_price.

The order is queued as a PendingOrder and fills on the first subsequent bar where candle.low ≤ limit_price. Fill price is limit_price, or the bar’s open if a gap-down open is already below the limit (realistic gap fill).

Example

use finance_query::backtesting::Signal;

// Buy if price dips to 98 within the next 5 bars.
let signal = Signal::buy_limit(ts, close, 98.0).expires_in_bars(5);

pub fn buy_stop(timestamp: i64, price: f64, stop_price: f64) -> Self

Create a stop buy order (breakout entry) — enter long when price breaks above stop_price.

Fills on the first subsequent bar where candle.high ≥ stop_price. Fill price is stop_price, or the bar’s open if a gap-up open is already above the stop (open price used instead).

Example

use finance_query::backtesting::Signal;

// Enter long on a breakout above 105.
let signal = Signal::buy_stop(ts, close, 105.0);

pub fn sell_limit(timestamp: i64, price: f64, limit_price: f64) -> Self

Create a limit sell order — enter short when price rallies to limit_price.

Fills on the first subsequent bar where candle.high ≥ limit_price. Fill price is limit_price, or the bar’s open if a gap-up open is already at or above the limit.

Example

use finance_query::backtesting::Signal;

// Short into a rally reaching 103.
let signal = Signal::sell_limit(ts, close, 103.0).expires_in_bars(10);

pub fn sell_stop(timestamp: i64, price: f64, stop_price: f64) -> Self

Create a stop sell order (breakdown entry) — enter short when price breaks below stop_price.

Fills on the first subsequent bar where candle.low ≤ stop_price. Fill price is stop_price, or the bar’s open if a gap-down open is already below the stop.

Example

use finance_query::backtesting::Signal;

// Short on a breakdown below 95.
let signal = Signal::sell_stop(ts, close, 95.0);

pub fn buy_stop_limit( timestamp: i64, price: f64, stop_price: f64, limit_price: f64, ) -> Self

Create a stop-limit buy order — triggered by a breakout above stop_price but capped at limit_price.

Fills when candle.high ≥ stop_price and the computed trigger price (bar open or stop_price, whichever is higher) does not exceed limit_price. If the bar gaps up above limit_price, the order cannot fill that bar and remains pending.

Example

use finance_query::backtesting::Signal;

// Breakout buy above 105, but reject fills above 107.
let signal = Signal::buy_stop_limit(ts, close, 105.0, 107.0);

pub fn expires_in_bars(self, bars: usize) -> Self

Set an expiry (in bars) for this pending limit/stop order.

When the order is not filled within bars bars after being placed, it is automatically cancelled. Has no effect on OrderType::Market signals.

Example

use finance_query::backtesting::Signal;

// Day order: fill or cancel after 1 bar.
let signal = Signal::buy_limit(ts, close, 98.0).expires_in_bars(1);

pub fn with_strength(self, strength: SignalStrength) -> Self

Set signal strength

pub fn with_reason(self, reason: impl Into<String>) -> Self

Set reason/description

pub fn with_metadata(self, metadata: SignalMetadata) -> Self

Set metadata

pub fn tag(self, name: impl Into<String>) -> Self

Attach a tag to this signal for post-hoc trade subgroup analysis.

Tags are propagated to [Trade::tags] when the position closes, enabling BacktestResult::trades_by_tag and metrics_by_tag queries. Multiple tags can be chained: .tag("breakout").tag("high_volume").

pub fn stop_loss(self, pct: f64) -> Self

Attach a per-trade stop-loss to this entry signal.

pct is the loss fraction relative to the entry price (0.0..=1.0). When set, the resulting position’s stop-loss overrides BacktestConfig::stop_loss_pct for the lifetime of that trade.

Example

use finance_query::backtesting::Signal;

// Stop out at -5% from entry, regardless of the config default.
let signal = Signal::long(ts, price).stop_loss(0.05);

pub fn take_profit(self, pct: f64) -> Self

Attach a per-trade take-profit to this entry signal.

pct is the profit fraction relative to the entry price (0.0..=1.0). When set, the resulting position’s take-profit overrides BacktestConfig::take_profit_pct for the lifetime of that trade.

Example

use finance_query::backtesting::Signal;

// Take profit at +15% from entry.
let signal = Signal::long(ts, price).take_profit(0.15);

pub fn trailing_stop(self, pct: f64) -> Self

Attach a per-trade trailing stop to this entry signal.

pct is the trail fraction from the position’s peak/trough price (0.0..=1.0). When set, the resulting position’s trailing stop overrides BacktestConfig::trailing_stop_pct for the lifetime of that trade.

Example

use finance_query::backtesting::Signal;

// Exit if price drops 3% from its peak since entry.
let signal = Signal::long(ts, price).trailing_stop(0.03);

Trait Implementations

impl Clone for Signal

fn clone(&self) -> Signal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Signal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Signal

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Signal

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Signal

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.