Add support for WEEK period

[nikhilwoodruff]

Hi there!

Firstly, thanks to the OpenFisca community for enabling us to use such a neat framework. In developing OpenFisca-UK, many variables including the majority of state benefits are specified in weekly amounts, which would be ideal to use as a standard period. I'm aware this has been discussed previously in #670 and #763.

As I understand it the main problems are identified in this comment:

About weeks, this is going to bring tricky questions about relationship between periods.

Right now, OpenFisca period model relies on the assumption that period fit well together. A YEAR is composed a 12 MONTHs . We could relatively easily add DAY, as a month is composed of 28 to 31 DAYs. We actually used to support them, but deprecated it as no one was using it.

However, WEEK is more challenging: they don't fit well in a month, nor in a year. And question will arise:

• If A's definition period is the week, can I calculate A for a year?
• If so, what do I do with the weeks that are only partially included in the year?
• Can we have a generic answer to the previous question, or is it going to be country-specific?

OpenFisca-UK has been relying off an implementation of the WEEK period in this fork, but it'd be good to see if this is something that can benefit other country packages. In our implementation, we answered the above questions with:

• If A's definition period is the week, can I calculate A for a year?

Yes.

• If so, what do I do with the weeks that are only partially included in the year?

Include the week of the first day of the year, and add weeks until we have reached (DAYS_IN_YEAR // 7) weeks. This also applies to months, respectively.

• Can we have a generic answer to the previous question, or is it going to be country-specific?

Use Monday as the first day of the week (this might be different in other countries)

However, one problem that the WEEK introduces that I can't think of a way around is that it wouldn't be entirely in line with other periods. In the documentation each period has a unique string to specify e.g. the month of 05-01-2021 ("2021-01"), and a month from 05-01-2021 ("month:2021-01-05"). The WEEK period would be ambiguous with DAY due to the datetime format, so we'd only be able to specify the week from the week start, but this doesn't actually prevent any features, as we would just need to start from the first day of the week.

Hopefully this has added something to the discussion - I know this feature would definitely benefit the UK model, and hopefully other countries, and I'd be interested to know what the general thoughts are on this.

TODO

• Fix bug in date validation Automatically validate parameter declaration dates #1005
• Add baseline test coverage for periods Extend set input #1174
• Add baseline test coverage for holders Extend set input #1174
• Add DateUnit to replace string date units Extend set input #1174
• Implement ISO Week Calendar Extend set input #1174
• Implement week offsets Extend set input #1174
• Implement week input dispatchs Extend set input #1174
• Implement week input divides Extend set input #1174
• Implement subperiods Extend set input #1174
• Split instant in two
• Implement ISO calendar instant parsing Implement ISO calendar instant parsing #1232
• Complete doc (code)
• Complete doc (mainstream)
• Simplify tests — or use a specific tool for brute-force testing
• Add typing to entities Add typing to entities #1231
• Add typing to periods Add typing to periods #1229
• Add typing to holders
• Add typing to variables
• Add typing to projectors docs: fix doc & type definitions in the projectors module #1221
• Add typing to simulations docs: improve testing in simulation builder #1222
• Add typing to populations
• Deprecate Instant.period Deprecate Instant.period #1142
• Deprecate obsolete methods
• Implement output dispatch Re-add support for dispatch/divide by days #1143
• Implement output divide Re-add support for dispatch/divide by days #1143
• Adapt holders
• Adapt variables
• Adapt populations
• Fix axes Fix axes expand mecanism #933 Extract axes from SimulationBuilder #996
• Fix entity instatiation fix: require fully specifing entities when expanding axes #1202
• Extract & test simulation rules docs: improve testing in simulation builder #1222
• Adapt simulations

[sandcha]

Thank you @nikhilwoodruff for this description!
I'm wondering if we couldn't use the week number in the year (from week n°1 to week n°52) to switch between periods and manage offsets. 🤔
Do you have an example in the UK model where you need to switch from a period to another? We could use it as real situation to test different syntax options.

[nikhilwoodruff]

Thanks @sandcha - here's an example of a weekly-defined variable we have in the UK model, for Child Benefit. I think that'd be good, though it probably does keep the problem of weeks being truncated by the start and end days of each year?

[bonjourmauko]

I was taking a look at this, which seems interesting for fiscal scenarios https://en.wikipedia.org/wiki/ISO_week_date