Calculating The Average Time Of Day Using The Circular Mean And Mellifera

A few weeks ago I was wondering what the average time of day was when making Git commits on my personal programming projects. Some of these projects, such as Sunder, have been primarily developed in my free time during the evenings after working hours at my then full-time job, while other projects, such as Mellifera, have been primarily developed during the day while working at my current part-time job with more flexible hours. It would be interesting to see if the actual commit times to these projects matched my intuition about when I felt like I was working on those projects, so I wrote a Mellifera program to calculate just that.

Every time that you make a commit with git commit, the current time is stored as the author date within the commit. You can check this author date with git log using:

~/sources/mellifera$ git log -1 --format=fuller | head -n 5
commit 1e6f5cb68ac3a06b3572f15a1f47fd201d2a6da3
Author:     ashn <me@ashn.dev>
AuthorDate: Tue Jun 30 09:44:30 2026 -0400
Commit:     ashn <me@ashn.dev>
CommitDate: Tue Jun 30 09:44:30 2026 -0400

In this case, the most recent commit to Mellifera occurred on Tuesday June 30th at 9:44 AM. This is kind of a nightmare to parse, but using the %aI format specifier, we can have git log spit out this time in an ISO 8601 date and time with UTC offset:

~/sources/mellifera$ git log -1 --format='%aI'
2026-06-30T09:44:30-04:00

And if we do that for the full log, we can get a list of these ISO 8601 date and times as a list with one datetime per line:

~/sources/mellifera$ git log --format='%aI' | head -n10 # 10 commits for brevity
2026-06-30T09:44:30-04:00
2026-06-29T02:02:34-04:00
2026-06-25T15:30:42-04:00
2026-06-24T20:37:15-04:00
2026-06-24T18:19:18-04:00
2026-06-22T11:27:11-04:00
2026-06-22T10:35:51-04:00
2026-06-19T07:16:22-04:00
2026-06-17T14:21:44-04:00
2026-06-11T11:33:28-04:00

Normalizing these times to UTC is also relatively easy, since the UTC offset is included in the datetime string:

let times = ```
2026-06-30T09:44:30-04:00
2026-06-29T02:02:34-04:00
2026-06-25T15:30:42-04:00
2026-06-24T20:37:15-04:00
2026-06-24T18:19:18-04:00
2026-06-22T11:27:11-04:00
2026-06-22T10:35:51-04:00
2026-06-19T07:16:22-04:00
2026-06-17T14:21:44-04:00
2026-06-11T11:33:28-04:00
```;

let datetimes = times.trim().split("\n");
println($"input datetimes: {datetimes}");

# Transforms an ISO 8601 date and time with offset:
#
#   YYYY-MM-DDTHH:MM:SS+XH:YM
#
# into a normalized UTC time with hours, minutes, and seconds in the form:
#
#   {.h = HH - XH, .m = MM - YM, .s = SS}
let iso8601_into_hms = function(s) {
    # YYYY-MM-DDTHH:MM:SS+XH:YM -> HH+XH MM+YM SS
    if s =~ r`\d{4}-\d{2}-\d{2}T(\d{2}):(\d{2}):(\d{2})([+-])(\d{2}):(\d{2})` {
        return {
            .h = number::init($1) - number::init($"{$4}{$5}"),
            .m = number::init($2) - number::init($"{$4}{$6}"),
            .s = number::init($3),
        };
    }
    error $`expected ISO 8601 date and time with offset, received {s}`;
};
let datetimes_hms = datetimes.map(iso8601_into_hms);
println($"datetimes (UTC in HMS): {datetimes_hms}");

Okay, so we have all of these datetimes normalized and just need to average them. Simple right? Well not so fast, as there is a hidden gotcha here. Imagine for a moment that we only have two datetimes to average: one at 11 PM on some day and another at 1 AM the next day. Intuitively, we know that the average time between 11 PM and 1 AM is midnight (00:00:00 in 24 hour time), as midnight sits right between 11 and 1 on a clock face.

However, if we use the normal formula for average, average = sum(values)/count(values), then we will end up with an average time of 12 o'clock noon (12:00:00) instead of 12 o'clock midnight (00:00:00)!

let times = ```
2026-07-01T01:00:00+00:00
2026-06-30T23:00:00+00:00
```;

let datetimes = times.trim().split("\n");
println($"input datetimes: {datetimes}");

# Ignore minutes and seconds for demonstration purposes...
let sum = 0;
for hms in datetimes_hms {
    sum = sum + hms.h;
}
let avg = sum / datetimes_hms.count();
println($"average datetime hour: {avg}");
println("Oh no! This is 12:00 noon, not 00:00 midnight! 🙁");

This occurs because the normal formula for average, known as the arithmetic mean, only works for numbers in a non-modular number system, such as the real numbers. Our measurements, the time of day, occur as part of a repeating 24 hour cycle, which makes the arithmetic mean practically meaningless (pun-intended).

Thankfully, this is already a solved problem. For modular number systems, such as a 24 hour clock, we can use the circular mean, which works as an average for this kind of cyclic data. The algorithm for the circular mean is as follows:

Scale HMS data into the number of seconds since midnight.
Map the seconds since midnight data onto the range [0, 2π].
Take the cosine and sine of each measurement to get the x and y Cartesian coordinates.
Find the arithmetic mean of the x and y coordinates for all those measurements.
Transform the average x and y coordinates back into a radial value with atan2.
Map the radial value in the range [0, 2π] back into the seconds since midnight.

As code, this algorithm takes the following form, which we can see correctly produces the midnight (00:00:00 UTC) result for the circular mean of 11 PM and 1 AM:

let times = ```
2026-07-01T01:00:00+00:00
2026-06-30T23:00:00+00:00
```;

let datetimes = times.trim().split("\n");
println($"input datetimes: {datetimes}");

let datetimes_hms = datetimes.map(iso8601_into_hms);
println($"datetimes (UTC in HMS): {datetimes_hms}");

let SECONDS_PER_MINUTE = 60;
let SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE;
let SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;

# Transforms a UTC time specified in hours, minutes, and seconds in the form:
#
#   {.h = HH, .m = MM, .s = SS}
#
# into the equivalent time of day as the number of seconds since midnight UTC.
let hms_into_seconds = function(hms) {
    return hms.h * SECONDS_PER_HOUR + hms.m * SECONDS_PER_MINUTE + hms.s;
};

let datetimes_sec = datetimes_hms.map(hms_into_seconds);
println($"datetimes (seconds since UTC midnight): {datetimes_sec}");

# Transforms a time of day specified by the number of seconds since midnight
# into radians where 0 and 2π radians are equivalent to midnight.
let seconds_into_radians = function(sec) {
    # y radians = 2π radians   1 day                     x seconds
    #             ---------- * ----------------------- *
    #             1 day        SECONDS_PER_DAY seconds
    return (2 * math::pi) / SECONDS_PER_DAY * sec;
};

let datetimes_rad = datetimes_sec.map(seconds_into_radians);
println($"datetimes (radians): {datetimes_rad}");

# Transforms an angle in radians into x and y Cartesian coordinates.
let radians_into_cartesian = function(rad) {
    return {
        .x = math::cos(rad),
        .y = math::sin(rad),
    };
};

let datetimes_xy = datetimes_rad.map(radians_into_cartesian);
println($"datetimes (Cartesian coordinates): {datetimes_xy}");

# Transforms a time of day specified in radians with 0 and 2π radians denoting
# midnight into the number of seconds since midnight.
let radians_into_seconds = function(rad) {
    # y seconds = SECONDS_PER_DAY seconds   1 day        x radians
    #             ----------------------- * ---------- *
    #             1 day                     2π radians
    let raw = SECONDS_PER_DAY / (2 * math::pi) * rad;
    return ((raw % SECONDS_PER_DAY) + SECONDS_PER_DAY) % SECONDS_PER_DAY;
};

let mean_sec = radians_into_seconds(mean_rad);
println($"mean datetime (seconds): {mean_sec}");

# Transforms the time of day as the number of seconds since midnight UTC into a
# UTC time specified in hours, minutes, and seconds in the form:
#
#   {.h = HH, .m = MM, .s = SS}
let seconds_into_hms = function(sec) {
    let h = math::floor(sec / SECONDS_PER_HOUR);
    let m = math::floor((sec % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE);
    let s = math::floor(sec % SECONDS_PER_MINUTE);
    return {.h = h, .m = m, .s = s};
};
let mean_hms = seconds_into_hms(mean_sec);
println($"mean datetime (HMS): {mean_hms}");

println($"{mean_hms.h.format("02d")}:{mean_hms.m.format("02d")}:{mean_hms.s.format("02d")} UTC");

And if we plug back in the original 10 time measurements from the Mellifera repository's git log, then we get a convincing looking 16:30 UTC (i.e. 12:30 EDT) for the average commit time.

# The rest of the existing code...
let datetimes = times.trim().split("\n");
println($"input datetimes: {datetimes}");