Earnings Date Helper

RSS

Syntax

public static class EarningsDate

Description

EarningsDate is a static class that has methods to determine earnings events for backtesting and also upcoming earnings releases for live EOD trading. Since EarningsDate is a static class, it's not required to create an object instance using "new". With a "using" reference to Community.Components, access EarningsDate methods (below) by direct calls as shown in the Example.

Method Syntax

public static bool EarningsDate.InWindow(WealthScript ws, int bar, string earningsString, int barsBefore, int barsAfter)

Parameter Description

ws	The WealthScript instance. Pass this.
bar	The current bar number.
earningsString	A fundamental item string that can be referenced to determine past earnings dates. Be sure to use an item that is reported quarterly. Examples for the Zacks Adjusted Earnings fundamental provider: "[z] Zacks Adjusted Earnings"
barsBefore, barsAfter	The number of days before and/or after the earnings date to be considered in the earnings window. For just the earnings date itself, pass 0 for both parameters.

Description

InWindow returns true if date of the bar passed to the method is within the "earnings window", otherwise false. The earnings window consists of the earnings date and contains the specified number of days before and/or after it. Use InWindow for both backtesting and live/EOD trading. Past earnings dates are obtained from the fundamental provider (6 years max lookback for Fidelity), whereas earnings dates in the future are accessed using the GetNextUseCache method. See GetNextUseCache below for more information.

Notes

InWindow first checks if a file named EarningsDateIgnore.txt exists in the user \Data folder. If you have ETFs mixed in your DataSet, you should add them to this file so that time is not wasted searching for their earnings dates. A sample file is attached that you can add to your Data folder. ETF symbols can be separated by whitespaces, tabs, or new lines.
InWindow employs the GetNext* methods below. Therefore, unless you need to access a future earnings release date directly, it not required to use the GetNext* methods.

Method Syntax

public static DateTime EarningsDate.GetNextUseCache(string symbol, DateTime lastProviderDate)

Parameter Description

symbol	The symbol whose next earnings date you want to obtain.
lastProviderDate	The earning's date reported most recently by the fundamental provider.

Description

GetNextUseCache accesses a bulk list of U.S. earnings dates to initially populate the cache file (EarningsDateCache.txt) in the user's \Data folder. It also uses the list to estimate and cache future earnings dates about 6 weeks in advance. When within 10 days of the cached date, the estimate is updated by the GetNext/GetNext2 methods. The resulting update is cached and not requested again until following the earnings release. The accuracy of the date is dependent on the GetNext providers, but to further ensure that your Strategy detects earnings events, use the InWindow method (above).

Due to the way GetNextUseCache works, the method may seem very slow the first time you run it on a large DataSet. All subsequent runs should be much quicker.

Method Syntax

public static DateTime EarningsDate.GetNext(string symbol, bool returnTimestamp = false)
public static DateTime EarningsDate.GetNext2(string symbol)

Parameter Description

symbol	The symbol whose next earnings date you want to obtain.
returnTimestamp	(Optional) Return the true time stamp of an earnings release

Description

GetNext first checks for an upcoming earnings date from earningswhispers.com. If not available, it automatically calls the GetNext2 method, which accesses money.cnn.com for the symbol's earnings release date.

As of v2018.03 of C.Components, GetNext (only) can optionally return the true timestamp of an earnings release to determine when it should happen (e.g. while the market is open or after hours).

Example

The Example demonstrates how to access the next earnings date for display in the chart window as well as how to use the InWindow method, which can be used to filter trading signals that occur in the "earnings date window".


using System;
using System.Collections.Generic;
using System.Text;
using System.Drawing;
using WealthLab;
using Community.Components; /*** Requires installation of Community.Components Extension from www.wealth-lab.com > Extensions ***/

namespace WealthLab.Strategies
{
	public class EarningsDateDemo : WealthScript
	{
		protected override void Execute()
		{	
			/* Display the next earnings release date in the chart */
			DateTime nextReportDate = new DateTime(2010, 1, 1);
			FundamentalItem fi = GetFundamentalItem (Bars.Count - 1, Bars.Symbol, "earnings per share");
			if (fi != null) 
			{
				nextReportDate = EarningsDate.GetNextUseCache(Bars.Symbol, fi.Date);
				PrintDebug(nextReportDate.ToShortDateString());
			}	
			else
			{				
				nextReportDate = EarningsDate.GetNextUseCache(Bars.Symbol, nextReportDate);
			}
			DrawLabel(PricePane, "Next Earnings: " + nextReportDate.ToShortDateString() );
			
			
			/* Highlight the "In Window" bars */
			for(int bar = 20; bar < Bars.Count; bar++)
			{
				if (EarningsDate.InWindow(this, bar, "z Zacks Adjusted Earnings", 2, 1))
					SetBackgroundColor(bar, Color.FromArgb(30, Color.Red));
			}
		}
	}
}