Convert DateTime to Julian Date in C# (ToOADate Safe?)
I need to convert from a standard Gregorian date to a Julian day number.
I've seen nothing documented in C# to do this directly, but I have found many posts (while Googling) suggesting the use of ToOADate.
The documentation on ToOADate does not suggest this as a valid conversion method for Julian dates.
Can anyone clarify if this function will perform conversion accurately, or perhaps a more appropriate method to convert DateTime to a Julian formatted string.
This provides me with the expected number when validated against Wikipedia's Julian Day page
public static long ConvertToJulian(DateTime Date)
{
int Month = Date.Month;
int Day = Date.Day;
int Year = Date.Year;
if (Month < 3)
{
Month = Month + 12;
Year = Year - 1;
}
long JulianDay = Day + (153 * Month - 457) / 5 + 365 * Year + (Year / 4) - (Year / 100) + (Year / 400) + 1721119;
return JulianDay;
}
However, this is without an understanding of the magic numbers being used.
Thanks
References:
- DateTime.ToOADate Method
OADate is similar to Julian Dates, but uses a different starting point (December 30, 1899 vs. January 1, 4713 BC), and a different 'new day' point. Julian Dates consider noon to be the beginning of a new day, OADates use the modern definition, midnight.
The Julian Date of midnight, December 30, 1899 is 2415018.5. This method should give you the proper values:
public static double ToJulianDate(this DateTime date)
{
return date.ToOADate() + 2415018.5;
}
As for the algorithm:
-
if (Month < 3) ...: To make the magic numbers work our right, they're putting February at the 'end' of the year. -
(153 * Month - 457) / 5: Wow, that's some serious magic numbers.- Normally, the number of days in each month is 31 28 31 30 31 30 31 31 30 31 30 31, but after that adjustment in the if statement, it becomes 31 30 31 30 31 31 30 31 30 31 31 28. Or, subtract 30 and you end up with 1 0 1 0 1 1 0 1 0 1 1 -2. They're creating that pattern of 1s and 0s by doing that division in integer space.
- Re-written to floating point, it would be
(int)(30.6 * Month - 91.4). 30.6 is the average number of days per month, excluding February (30.63 repeating, to be exact). 91.4 is almost the number of days in 3 average non-February months. (30.6 * 3 is 91.8). - So, let's remove the 30, and just focus on that 0.6 days. If we multiply it by the number of months, and then truncate to an integer, we'll get a pattern of 0s and 1s.
- 0.6 * 0 = 0.0 -> 0
- 0.6 * 1 = 0.6 -> 0 (difference of 0)
- 0.6 * 2 = 1.2 -> 1 (difference of 1)
- 0.6 * 3 = 1.8 -> 1 (difference of 0)
- 0.6 * 4 = 2.4 -> 2 (difference of 1)
- 0.6 * 5 = 3.0 -> 3 (difference of 1)
- 0.6 * 6 = 3.6 -> 3 (difference of 0)
- 0.6 * 7 = 4.2 -> 4 (difference of 1)
- 0.6 * 8 = 4.8 -> 4 (difference of 0)
- See that pattern of differences in the right? That's the same pattern in the list above, the number of days in each month minus 30. The subtraction of 91.8 would compensate for the number of days in the first three months, that were moved to the 'end' of the year, and adjusting it by 0.4 moves the successive differences of 1 (0.6 * 4 and 0.6 * 5 in the above table) to align with the adjacent months that are 31 days.
- Since February is now at the 'end' of the year, we don't need to deal with its length. It could be 45 days long (46 on a leap year), and the only thing that would have to change is the constant for the number of days in a year, 365.
- Note that this relies on the pattern of 30 and 31 month days. If we had two months in a row that were 30 days, this would not be possible.
-
365 * Year: Days per year -
(Year / 4) - (Year / 100) + (Year / 400): Plus one leap day every 4 years, minus one every 100, plus one every 400. -
+ 1721119: This is the Julian Date of March 2nd, 1 BC. Since we moved the 'start' of the calendar from January to March, we use this as our offset, rather than January 1st. Since there is no year zero, 1 BC gets the integer value 0. As for why March 2nd instead of March 1st, I'm guessing that's because that whole month calculation was still a little off at the end. If the original writer had used- 462instead of- 457(- 92.4instead of- 91.4in floating point math), then the offset would have been to March 1st.
While the method
public static double ToJulianDate(this DateTime date) { return date.ToOADate() + 2415018.5; }
works for modern dates, it has significant shortcomings.
The Julian date is defined for negative dates - i.e, BCE (before common era) dates and is common in astronomical calculations. You cannot construct a DateTime object with the year less than 0, and so the Julian Date cannot be computed for BCE dates using the above method.
The Gregorian calendar reform of 1582 put an 11 day hole in the calendar between October 4th and the 15th. Those dates are not defined in either the Julian calendar or the Gregorian calendar, but DateTime accepts them as arguments. Furthermore, using the above method does not return the correct value for any Julian date. Experiments with using the System.Globalization.JulianCalendar.ToDateTime(), or passing the JulianCalendar era into the DateTime constructor still produce incorrect results for all dates prior to October 5, 1582.
The following routines, adapted from Jean Meeus' "Astronomical Algorithms", returns correct results for all dates starting from noon on January 1st, -4712, time zero on the Julian calendar. They also throw an ArgumentOutOfRangeException if an invalid date is passed.
public class JulianDate
{
public static bool isJulianDate(int year, int month, int day)
{
// All dates prior to 1582 are in the Julian calendar
if (year < 1582)
return true;
// All dates after 1582 are in the Gregorian calendar
else if (year > 1582)
return false;
else
{
// If 1582, check before October 4 (Julian) or after October 15 (Gregorian)
if (month < 10)
return true;
else if (month > 10)
return false;
else
{
if (day < 5)
return true;
else if (day > 14)
return false;
else
// Any date in the range 10/5/1582 to 10/14/1582 is invalid
throw new ArgumentOutOfRangeException(
"This date is not valid as it does not exist in either the Julian or the Gregorian calendars.");
}
}
}
static private double DateToJD(int year, int month, int day, int hour, int minute, int second, int millisecond)
{
// Determine correct calendar based on date
bool JulianCalendar = isJulianDate(year, month, day);
int M = month > 2 ? month : month + 12;
int Y = month > 2 ? year : year - 1;
double D = day + hour/24.0 + minute/1440.0 + (second + millisecond / 1000.0)/86400.0;
int B = JulianCalendar ? 0 : 2 - Y/100 + Y/100/4;
return (int) (365.25*(Y + 4716)) + (int) (30.6001*(M + 1)) + D + B - 1524.5;
}
static public double JD(int year, int month, int day, int hour, int minute, int second, int millisecond)
{
return DateToJD(year, month, day, hour, minute, second, millisecond);
}
static public double JD(DateTime date)
{
return DateToJD(date.Year, date.Month, date.Day, date.Hour, date.Minute, date.Second, date.Millisecond);
}
}
The explanation by David Yaw is spot on, but calculation of the cumulative number of days of the year for the months prior to the given month is anti-intuitive. If you prefer an array of integers to make the algorithm more clear then this will do:
/*
* convert magic numbers created by:
* (153*month - 457)/5)
* into an explicit array of integers
*/
int[] CumulativeDays = new int[]
{
-92 // Month = 0 (Should not be accessed by algorithm)
, -61 // Month = 1 (Should not be accessed by algorithm)
, -31 // Month = 2 (Should not be accessed by algorithm)
, 0 // Month = 3 (March)
, 31 // Month = 4 (April)
, 61 // Month = 5 (May)
, 92 // Month = 6 (June)
, 122 // Month = 7 (July)
, 153 // Month = 8 (August)
, 184 // Month = 9 (September)
, 214 // Month = 10 (October)
, 245 // Month = 11 (November)
, 275 // Month = 12 (December)
, 306 // Month = 13 (January, next year)
, 337 // Month = 14 (February, next year)
};
and the first thre lines of the calculation then become:
int julianDay = day
+ CumulativeDays[month]
+ 365*year
+ (year/4)
The expression
(153*month - 457)/5)
though produces the exact same sequence same integers as the array above for values in the range: 3 to 14; inclusive and does so with no storage requirements. The lack of storage requirements is only virtue in calculating the cumulative number of days in such and obfuscated way.
If someone need to convert from Julian date to DateTime , see below :
public static DateTime FromJulianDate(double julianDate)
{
return DateTime.FromOADate(julianDate - 2415018.5);
}
My code for modified Julian Date uses the same algorithm but a different magic number on the end so that the resulting value matches the Modified Julian Date shown on Wikipedia. I have been using this same algorithm for at least 10 years as the key for daily time series (originally in Java).
public static int IntegerDate(DateTime date)
{
int Month = date.Month;
int Day = date.Day;
int Year = date.Year;
if (Month < 3)
{
Month = Month + 12;
Year = Year - 1;
}
//modified Julian Date
return Day + (153 * Month - 457) / 5 + 365 * Year + (Year / 4) - (Year / 100) + (Year / 400) - 678882;
}
The reverse calculation has more magic numbers for your amusement:
public static DateTime FromDateInteger(int mjd)
{
long a = mjd + 2468570;
long b = (long)((4 * a) / 146097);
a = a - ((long)((146097 * b + 3) / 4));
long c = (long)((4000 * (a + 1) / 1461001));
a = a - (long)((1461 * c) / 4) + 31;
long d = (long)((80 * a) / 2447);
int Day = (int)(a - (long)((2447 * d) / 80));
a = (long)(d / 11);
int Month = (int)(d + 2 - 12 * a);
int Year = (int)(100 * (b - 49) + c + a);
return new DateTime(Year, Month, Day);
}