English EN
View on GitHub

Skewness Commodity

The Skewness Commodity strategy ranks commodity futures by the skewness of their return distribution. Contracts with positive skewness are favored for long positions, while those with strongly negative skewness are sold short, assuming extreme downside moves will mean revert.

Details

  • Entry Criteria: Ranking by historical return skewness.
  • Long/Short: Both directions.
  • Exit Criteria: Periodic rebalance.
  • Stops: No explicit stop.
  • Default Values:
    • CandleType = TimeSpan.FromMinutes(5).TimeFrame()
  • Filters:
    • Category: Statistical
    • Direction: Both
    • Indicators: Price based
    • Stops: No
    • Complexity: Intermediate
    • Timeframe: Medium-term
    • Seasonality: No
    • Neural Networks: No
    • Divergence: No
    • Risk Level: Medium
using System;
using System.Collections.Generic;
using System.Linq;

using Ecng.Common;

using StockSharp.Algo.Indicators;
using StockSharp.Algo.Strategies;
using StockSharp.BusinessEntities;
using StockSharp.Configuration;
using StockSharp.Messages;

namespace StockSharp.Samples.Strategies;

/// <summary>
/// Skewness-based commodity strategy that trades the primary commodity when its return skewness diverges from a benchmark commodity.
/// </summary>
public class SkewnessCommodityStrategy : Strategy
{
	private readonly StrategyParam<string> _security2Id;
	private readonly StrategyParam<int> _windowLength;
	private readonly StrategyParam<int> _normalizationPeriod;
	private readonly StrategyParam<decimal> _entryThreshold;
	private readonly StrategyParam<decimal> _exitThreshold;
	private readonly StrategyParam<int> _cooldownBars;
	private readonly StrategyParam<decimal> _stopLoss;
	private readonly StrategyParam<DataType> _candleType;

	private Security _benchmark = null!;
	private SimpleMovingAverage _spreadAverage = null!;
	private StandardDeviation _spreadDeviation = null!;
	private readonly Queue<decimal> _primaryReturns = [];
	private readonly Queue<decimal> _benchmarkReturns = [];
	private decimal? _previousPrimaryClose;
	private decimal? _previousBenchmarkClose;
	private decimal? _previousZScore;
	private decimal _latestPrimarySkewness;
	private decimal _latestBenchmarkSkewness;
	private bool _primaryUpdated;
	private bool _benchmarkUpdated;
	private int _cooldownRemaining;

	public string Security2Id
	{
		get => _security2Id.Value;
		set => _security2Id.Value = value;
	}

	public int WindowLength
	{
		get => _windowLength.Value;
		set => _windowLength.Value = value;
	}

	public int NormalizationPeriod
	{
		get => _normalizationPeriod.Value;
		set => _normalizationPeriod.Value = value;
	}

	public decimal EntryThreshold
	{
		get => _entryThreshold.Value;
		set => _entryThreshold.Value = value;
	}

	public decimal ExitThreshold
	{
		get => _exitThreshold.Value;
		set => _exitThreshold.Value = value;
	}

	public int CooldownBars
	{
		get => _cooldownBars.Value;
		set => _cooldownBars.Value = value;
	}

	public decimal StopLoss
	{
		get => _stopLoss.Value;
		set => _stopLoss.Value = value;
	}

	public DataType CandleType
	{
		get => _candleType.Value;
		set => _candleType.Value = value;
	}

	public SkewnessCommodityStrategy()
	{
		_security2Id = Param(nameof(Security2Id), Paths.HistoryDefaultSecurity2)
			.SetDisplay("Benchmark Security Id", "Identifier of the benchmark commodity", "General");

		_windowLength = Param(nameof(WindowLength), 20)
			.SetRange(5, 120)
			.SetDisplay("Window Length", "Lookback period used to estimate return skewness", "Indicators");

		_normalizationPeriod = Param(nameof(NormalizationPeriod), 16)
			.SetRange(5, 120)
			.SetDisplay("Normalization Period", "Lookback period used to normalize the skewness spread", "Indicators");

		_entryThreshold = Param(nameof(EntryThreshold), 1.1m)
			.SetRange(0.2m, 5m)
			.SetDisplay("Entry Threshold", "Z-score threshold required to open a position", "Signals");

		_exitThreshold = Param(nameof(ExitThreshold), 0.25m)
			.SetRange(0m, 2m)
			.SetDisplay("Exit Threshold", "Z-score threshold required to close a position", "Signals");

		_cooldownBars = Param(nameof(CooldownBars), 8)
			.SetRange(0, 120)
			.SetDisplay("Cooldown Bars", "Closed candles to wait before another position change", "Risk");

		_stopLoss = Param(nameof(StopLoss), 3m)
			.SetRange(0.5m, 10m)
			.SetDisplay("Stop Loss %", "Stop loss percentage", "Risk");

		_candleType = Param(nameof(CandleType), TimeSpan.FromHours(4).TimeFrame())
			.SetDisplay("Candle Type", "Time frame for candles", "General");
	}

	/// <inheritdoc />
	public override IEnumerable<(Security sec, DataType dt)> GetWorkingSecurities()
	{
		if (Security != null)
			yield return (Security, CandleType);

		if (!Security2Id.IsEmpty())
			yield return (new Security { Id = Security2Id }, CandleType);
	}

	/// <inheritdoc />
	protected override void OnReseted()
	{
		base.OnReseted();

		_benchmark = null!;
		_spreadAverage = null!;
		_spreadDeviation = null!;
		_primaryReturns.Clear();
		_benchmarkReturns.Clear();
		_previousPrimaryClose = null;
		_previousBenchmarkClose = null;
		_previousZScore = null;
		_latestPrimarySkewness = 0m;
		_latestBenchmarkSkewness = 0m;
		_primaryUpdated = false;
		_benchmarkUpdated = false;
		_cooldownRemaining = 0;
	}

	/// <inheritdoc />
	protected override void OnStarted2(DateTime time)
	{
		base.OnStarted2(time);

		if (Security == null)
			throw new InvalidOperationException("Primary security is not specified.");

		if (Security2Id.IsEmpty())
			throw new InvalidOperationException("Benchmark security identifier is not specified.");

		_benchmark = this.LookupById(Security2Id) ?? new Security { Id = Security2Id };
		_spreadAverage = new SimpleMovingAverage { Length = NormalizationPeriod };
		_spreadDeviation = new StandardDeviation { Length = NormalizationPeriod };

		var primarySubscription = SubscribeCandles(CandleType, security: Security);
		var benchmarkSubscription = SubscribeCandles(CandleType, security: _benchmark);

		primarySubscription.Bind(ProcessPrimaryCandle).Start();
		benchmarkSubscription.Bind(ProcessBenchmarkCandle).Start();

		StartProtection(new Unit(2, UnitTypes.Percent), new Unit(StopLoss, UnitTypes.Percent));
	}

	private void ProcessPrimaryCandle(ICandleMessage candle)
	{
		if (candle.State != CandleStates.Finished)
			return;

		if (UpdateReturns(_primaryReturns, candle.ClosePrice, ref _previousPrimaryClose) is null)
			return;

		_latestPrimarySkewness = CalculateSkewness(_primaryReturns);
		_primaryUpdated = true;
		TryProcessSpread(candle.OpenTime);
	}

	private void ProcessBenchmarkCandle(ICandleMessage candle)
	{
		if (candle.State != CandleStates.Finished)
			return;

		if (UpdateReturns(_benchmarkReturns, candle.ClosePrice, ref _previousBenchmarkClose) is null)
			return;

		_latestBenchmarkSkewness = CalculateSkewness(_benchmarkReturns);
		_benchmarkUpdated = true;
		TryProcessSpread(candle.OpenTime);
	}

	private decimal? UpdateReturns(Queue<decimal> queue, decimal closePrice, ref decimal? previousClose)
	{
		if (previousClose is not decimal previous || previous <= 0m)
		{
			previousClose = closePrice;
			return null;
		}

		var ret = (closePrice - previous) / previous;
		previousClose = closePrice;

		if (queue.Count == WindowLength)
			queue.Dequeue();

		queue.Enqueue(ret);
		return ret;
	}

	private static decimal CalculateSkewness(IEnumerable<decimal> returns)
	{
		var values = returns.ToArray();
		if (values.Length < 3)
			return 0m;

		var mean = values.Average();
		var variance = values.Select(value => (value - mean) * (value - mean)).Average();
		if (variance <= 0m)
			return 0m;

		var deviation = (decimal)Math.Sqrt((double)variance);
		var thirdMoment = values.Select(value => (value - mean) * (value - mean) * (value - mean)).Average();
		return thirdMoment / (deviation * deviation * deviation);
	}

	private void TryProcessSpread(DateTime time)
	{
		if (!_primaryUpdated || !_benchmarkUpdated || _primaryReturns.Count < WindowLength || _benchmarkReturns.Count < WindowLength)
			return;

		_primaryUpdated = false;
		_benchmarkUpdated = false;

		var spread = _latestBenchmarkSkewness - _latestPrimarySkewness;
		var mean = _spreadAverage.Process(spread, time, true).ToDecimal();
		var deviation = _spreadDeviation.Process(spread, time, true).ToDecimal();

		if (!_spreadAverage.IsFormed || !_spreadDeviation.IsFormed || deviation <= 0m)
			return;

		if (!IsFormedAndOnlineAndAllowTrading())
			return;

		if (_cooldownRemaining > 0)
			_cooldownRemaining--;

		var zScore = (spread - mean) / deviation;
		var bullishEntry = _previousZScore is decimal previousBullish && previousBullish < EntryThreshold && zScore >= EntryThreshold;
		var bearishEntry = _previousZScore is decimal previousBearish && previousBearish > -EntryThreshold && zScore <= -EntryThreshold;

		if (_cooldownRemaining == 0 && Position == 0)
		{
			if (bullishEntry)
			{
				BuyMarket();
				_cooldownRemaining = CooldownBars;
			}
			else if (bearishEntry)
			{
				SellMarket();
				_cooldownRemaining = CooldownBars;
			}
		}
		else if (Position > 0 && zScore <= ExitThreshold)
		{
			SellMarket(Position);
			_cooldownRemaining = CooldownBars;
		}
		else if (Position < 0 && zScore >= -ExitThreshold)
		{
			BuyMarket(Math.Abs(Position));
			_cooldownRemaining = CooldownBars;
		}

		_previousZScore = zScore;
	}
}