proposal: time: add Epiweek

[jmeekhof]

I'd like to propose adding epiweek to the time package.
An epiweek is almost identical to an ISO Week. The only difference is that an epiweek begins on Sunday and an ISO Week begins on Monday.

Adding this functionality should be trivial and would be beneficial for certain branches of work.

[ianlancetaylor]

This seems easy to write in a third party package. See https://golang.org/doc/faq#x_in_std.

[jmeekhof]

Implementation wise, it's identical to ISOWeek, and that is in the standard package. The only difference is you pivot on Wednesday instead of Thursday. Access to the private abs() methods make the implementation trivial in the package.

func (t Time) EpiWeek() (year, week int) {
	// According to the rule that the first calendar week of a calendar year is
	// the week including the first Thursday of that year, and that the last one is
	// the week immediately preceding the first calendar week of the next calendar year.

	// weeks start with Sunday
	// Sunday Monday Tuesday Wednesday Thursday Friday Saturday
	// 1      2       3         4        5      6        7
	// +3     +2      +1        0        -1     -2       -3
	// the offset to Wednesday
	abs := t.abs()
	d := Wednesday - absWeekday(abs)
	// handle Saturday
	if d == 4 {
		d = -3
	}
	// find the Wednesday of the calendar week
	abs += uint64(d) * secondsPerDay
	year, _, _, yday := absDate(abs, false)
	return year, yday/7 + 1
}

[ianlancetaylor]

Seems like an external package could use ISOWeek and adjust if January 1 is a Wednesday.

My point is that since this can be written in an external package, we need to justify adding it to the standard library. What is that justification? Ease of implementation is not a justification; new API requires building and testing and maintenance and requires people reading the package to read and understand the functionality. It's not free. Of course we should do it if it's important, but why is Epiweek important?

[jmeekhof]

Points are well put. Epiweeks is an epidemiological week. It is often used for counting weeks and for forecasting flu outbreaks across the country.

The question I would ask is, why was it considered important to add ISOWeek to the time package? If they're the same thing with a different starting day of the week, why wouldn't they be in the same package?

[ianlancetaylor]

Because ISO weeks are widely used. I don't know how widely used Epiweeks are. If they are only used by epidemiologists, then I'm not sure that they are widely used.

For example, there is a Wikipedia entry for ISO weeks (https://en.wikipedia.org/wiki/ISO_week_date) but as far as I can tell there is not one for Epiweeks.

[jmeekhof]

I wish the US epidemiologist used ISO weeks, it would make all of our lives easier. Epiweeks are mostly used in data science work, and you see support for this variation of week counting in languages such as R and Python.

https://rdrr.io/cran/lubridate/man/week.html

https://epiweeks.readthedocs.io/

https://www.cdc.gov/epiinfo/user-guide/check-code/epiweekfunctions.html

[ianlancetaylor]

The Python example is a third party package. The same could be done for Go.

[jmeekhof]

I implemented this as a third party package.
jmeekhof/epiweek