Correlation.cs

/*
 * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
 * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
*/
 
using System;
using QuantConnect.Data.Market;
 
namespace QuantConnect.Indicators
{
    /// <summary>
    /// The Correlation Indicator is a valuable tool in technical analysis, designed to quantify the degree of 
    /// relationship between the price movements of a target security (e.g., a stock or ETF) and a reference 
    /// market index. It measures how closely the target’s price changes are aligned with the fluctuations of 
    /// the index over a specific period of time, providing insights into the target’s susceptibility to market 
    /// movements.
    /// A positive correlation indicates that the target tends to move in the same direction as the market index, 
    /// while a negative correlation suggests an inverse relationship. A correlation close to 0 implies a weak or 
    /// no linear relationship.
    /// Commonly, the SPX index is employed as the benchmark for the overall market when calculating correlation, 
    /// ensuring a consistent and reliable reference point. This helps traders and investors make informed decisions 
    /// regarding the risk and behavior of the target security in relation to market trends.
    /// 
    /// The indicator only updates when both assets have a price for a time step. When a bar is missing for one of the assets, 
    /// the indicator value fills forward to improve the accuracy of the indicator.
    /// </summary>
    public class Correlation : DualSymbolIndicator<double>
    {
        /// <summary>
        /// Correlation type
        /// </summary>
        private readonly CorrelationType _correlationType;
 
        /// <summary>
        /// Gets a flag indicating when the indicator is ready and fully initialized
        /// </summary>
        public override bool IsReady => TargetDataPoints.IsReady && ReferenceDataPoints.IsReady;
 
        /// <summary>
        /// Creates a new Correlation indicator with the specified name, target, reference,  
        /// and period values
        /// </summary>
        /// <param name="name">The name of this indicator</param>
        /// <param name="targetSymbol">The target symbol of this indicator</param>
        /// <param name="period">The period of this indicator</param>
        /// <param name="referenceSymbol">The reference symbol of this indicator</param>
        /// <param name="correlationType">Correlation type</param>
        public Correlation(string name, Symbol targetSymbol, Symbol referenceSymbol, int period, CorrelationType correlationType = CorrelationType.Pearson)
            : base(name, targetSymbol, referenceSymbol, period)
        {
            // Assert the period is greater than two, otherwise the correlation can not be computed
            if (period < 2)
            {
                throw new ArgumentException($"Period parameter for Correlation indicator must be greater than 2 but was {period}");
            }
            WarmUpPeriod = period + (IsTimezoneDifferent ? 1 : 0);
            _correlationType = correlationType;
        }
 
        /// <summary>
        /// Creates a new Correlation indicator with the specified target, reference,  
        /// and period values
        /// </summary>
        /// <param name="targetSymbol">The target symbol of this indicator</param>
        /// <param name="period">The period of this indicator</param>
        /// <param name="referenceSymbol">The reference symbol of this indicator</param>
        /// <param name="correlationType">Correlation type</param>
        public Correlation(Symbol targetSymbol, Symbol referenceSymbol, int period, CorrelationType correlationType = CorrelationType.Pearson)
            : this($"Correlation({period})", targetSymbol, referenceSymbol, period, correlationType)
        {
        }
 
        /// <summary>
        /// Adds the closing price to the target or reference symbol's data set.
        /// </summary>
        /// <param name="input">The input value for this symbol</param>
        /// <exception cref="ArgumentException">Thrown if the input symbol is not the target or reference symbol.</exception>
        protected override void AddDataPoint(IBaseDataBar input)
        {
            if (input.Symbol == TargetSymbol)
            {
                TargetDataPoints.Add((double)input.Close);
            }
            else if (input.Symbol == ReferenceSymbol)
            {
                ReferenceDataPoints.Add((double)input.Close);
            }
            else
            {
                throw new ArgumentException($"The given symbol {input.Symbol} was not {TargetSymbol} or {ReferenceSymbol} symbol");
            }
        }
 
        /// <summary>
        /// Computes the correlation value usuing symbols values
        /// correlation values assing into _correlation property
        /// </summary>
        protected override void ComputeIndicator()
        {
            var newCorrelation = 0d;
            if (_correlationType == CorrelationType.Pearson)
            {
                newCorrelation = MathNet.Numerics.Statistics.Correlation.Pearson(TargetDataPoints, ReferenceDataPoints);
            }
            if (_correlationType == CorrelationType.Spearman)
            {
                newCorrelation = MathNet.Numerics.Statistics.Correlation.Spearman(TargetDataPoints, ReferenceDataPoints);
            }
            if (newCorrelation.IsNaNOrZero())
            {
                newCorrelation = 0;
            }
            IndicatorValue = Extensions.SafeDecimalCast(newCorrelation);
        }
    }
}