Add support for other time periods

[nigelcharman]

In this PR, we are attempting to code the NZ Compensation for Live Organ Donors Act 2016. This requires that weekly earnings are calculated.

Income in NZ is typically based on a Weekly, Fortnightly, 4 Weekly or Monthly basis.

OpenFisca Periods currently supports MONTH, YEAR and ETERNITY.

Ideally, we would allow the user to set as input variables the amount of each pay. The code would need to be changed to support this. We suggest that this would require periods of WEEK, FORTNIGHT and 4_WEEKS, in addition to MONTH.

For the output variable weekly_compensation_before_tax, we suggest that this is calculated for a specific point in time immediately after the final pay period which has been entered. This might require a DAY period to be allowed.

[benjello]

I am not opposed to the creation of new time periods.
But may be the definition of some very specific time period in country package and keep the more general one in core. To be crystal clear, i do think that the one proposed here are generic enough to be included in openfisca-core.

[MattiSG]

I'm wondering about FORTNIGHT and 4_WEEKS: should these be considered handled by WEEK?

In France, for example, some values are defined as MONTH yet have a value over a trimester.
@benjello @guillett how are these usually handled? If I declare an income every trimester, do I specify it in OpenFisca with a MONTH variable where I divide the value by 3 for each month in a trimester? Or do I set the value for the trimester in the first month of it and then set 0 for the two others? 🤔

[benjello]

For France, we need to compute the revenues over the last three months. We do not use a specific time period but a multiple of MONTH. We use some specific helpers like last_3_months (or so i am on m'y phone do.i can't easily check).

[fpagnoux]

@benjello @guillett how are these usually handled? If I declare an income every trimester, do I specify it in OpenFisca with a MONTH variable where I divide the value by 3 for each month in a trimester? Or do I set the value for the trimester in the first month of it and then set 0 for the two others? 🤔

This actually depend on the variable.
There is an opt-in that allows to set a variable value for a period bigger than its definition period.

If this opt-in has been activated, you can just declare the income for the trimester.
If this opt-in has not been activated, you can only declared monthly values.

[fpagnoux]

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?

Also, the concept of week itself may be tricky:

• Are we talking about any period of 7 days, or do weeks always start the same day?
• If so, which day is that?
• Can we have a generic answer to the previous question, or is it going to be country-specific?

[fpagnoux]

I'm wondering about FORTNIGHT and 4_WEEKS: should these be considered handled by WEEK?

It really depends on what you will need these periods for. In France, we handle rolling years, trimesters, rolling trimesters... But these are not valid definition period. I cannot create a variable that is defined on this type of periods. However, I can calculate a variable for a trimester (which is often summing the variable for the months contained in the trimester).

[fpagnoux]

In all case, if we were to rewrite the periods module, it would definitely be worth checking if there is not some well made Python library (a momentJS equivalent) that could give us the flexibility we need without having to reinvent the wheel.

But I'm not 100% sure that this library exist, or that it would fit our needs.

[nigelcharman]

@fpagnoux Even in the small piece of legislation we were working on, we saw different interpretations of week, so it's likely to be even more fine-grained, eg. act-specific . There may be an opportunity to roll some of the interpretations up to be more general, once they are well scoped.

The first interpretation we saw was for employees who are paid weekly. The assumption here was that there are 52 weeks in the year.

For self-employed folks, a week was defined as either a whole week or a part-week, which would normally lead to 53-week years, but could potentially mean a 54-week year if there was a part-week at both ends of the year. We weren't able to clarify whether this could actually happen. That might then depend on which day of the week a week started on.

@BrigetteM - do you have anything to add based on your reading of this legislation?

I should also note that our team are unlikely to continue developing this solution, which was created as part of a hackathon weekend. It might be picked up by someone else in future, as might work around the NZ tax system which may need to model this too.

[BrigetteM]

My comment to this is that it might be useful in this case to refer to a 'PeriodOfTime' (as already defined) therefore change the calculator to ask for the dates and then do a calculation:
i.e.: if from 01/05-08/05, return a 'weekly periods' of 2.
Just my thoughts.
There are several instances around the world of legislation that treats periods of time differently for the purposes of calculation. It could be useful to work through these and find a common approach to dealing with it.
ps: I just had a quick look at metalex (which is the basis from which legislation.gov.uk is made) and found they also just deal with dates, likely because they're far easier :-) I took a snapshot of it as I have it loaded in protege and have attached it here.

[fpagnoux]

they also just deal with dates, likely because they're far easier :-)

That is an interesting thought, thanks 🤔 . Declaring everything on a single day indeed may avoid all this period modeling. To keep in mind 🙂.

[BrigetteM]

To put into notes a conversation with Matti (and please forgive the social security bias), the areas I know of include: most European countries will pay pensions on the same day each month. This means that most times, the times between payments will be more than 4 weeks. To make it 'fair', there is a 13th 'bonus' payment, which really just helps to ensure pensioners receive their annual rate correctly (which is calculated annually and divided by 13 to arrive at the monthly rate (why? there are 52 weeks in a 'year' (a period from and to, not 365 days) and obviously, 13 is 52 divided by 4. Hence also I believe, the discussion above about advising of your income 4 times a year.
In Australia, social security is paid every 2 weeks, except in exceptional circumstances where it is paid weekly (same day each week/f/t). There is no bonus as 26 payments are made.
In Spain, they will calculate the rate based on what they think the cost of living increase is going to be. They also have a 13th payment, and then occasionally, when they really get the cost of living estimate wrong, they make an adjustment and pay a 14th payment. So this is a global example of legislation that exists that needs to be modelled and has issues with time periods. The calculations must be able to be coded, as I can explain them to you in this post and I think it makes sense.
In Australia, we have another funny thing about dates, which I explained to Matti- when calculating working life residence for the purposes of qualification, not payability (these are two separate things and this is also consistent around the world), we calculate the months of residence by dates (I think , this is a little hazy), then where a person has say 1 month and 1 day, then they are deemed to have 2 months. So this is the same mathematical/coding problem as the problem being discussed here. If you're interested, I can try to find references for each country's payment and qualification calculations (maybe just for one payment). Otherwise, hopefully these small examples will give you some good food for thought!

[Morendil]

Closing this, as #763 will serve as existence proof that Core does support "other" time periods, and possibly a template for doing so in Core. It's less clear how a particular country might code a period of time specific to its needs though.