Semantics of `change_on_boundary` in `ceiling_date`

[hadley]

I'm reasonably certain that change_on_bounary is really about whether the intervals are [) or (]. By correspondence with cut(), right would be a better name.

I also think it's a really really really bad idea to make the default value an option.

[vspinu]

right open or right closed? The fact that it's used in cut doesn't make it an intuitive name. The interval indirection complicates the logic, and for most people who face the problem of not ceiling on the boundary, spotting change_on_boundary should ring all relevant bells. I don't see that happening with right or even right_open.

As for defaults, I don't mind changing that. I find it ugly as well. But what is so "very^3" bad about it? It's just as bad or good as any other defaults in other functions that change the computation.

[hadley]

I think it's a suboptimal name currently because it's very long, and it doesn't connect to any bigger concepts. Sure right is not the most intuitive idea, but you'll encounter it in most of other places. Maybe a better option is to copy geom_histogram() and have closed = c("right", "left").

Having an option that changes the behaviour of computation is a terrible idea because it means an option set a very long way away in the code (potentially in another package) can affect computation. (i.e. if you ever use one of these functions in a package, you have to set it every time in order to ensure consistent behaviour). I feel very strongly about this because of many bad experiences with stringsAsFactors.

[vspinu]

I have removed the global option.

As to the name, that change has been released and I know for a fact that quite a few people are already using it (there are 5 related issues only on our github page). The naming was discussed in #390 and no-one came with a better name.

I don't think long name is a problem. It hardly matters with completion and you can always partial it in interactive work. I also think that if we decide to add similar option to floor_date it should have the same name. Any interval-inspired name will have to be different for symmetry reasons.

Your interpretation of open/close interval is also not quite a right model of what's happening. For instance when ceiling 2016-09-01 you would like to get 2016-10-01, it might appear that (...] is the right paradigm, but that would work only for first application of the function. For ceiling_date(ceiling_date(...)) you would need to mentally slide the left-open interval for each application of the function. If you prefer to think in terms of intervals, a sequence of open intervals would be a better mental model - (...)(...)....

To wrap up, if we are to change the name it must be much, much better to be worth the pain of change. So I am closing this one for now; feel free to re-open if you have further ideas.

[shrektan]

I don't use the global option personally. It's ok for me. Another solution would be to define a new function name with change-on-boundary being setting to TRUE…

[vspinu]

@hadley, how about sticky = TRUE instead of change_on_boundary? It's short and reasonably suggestive in my opinion.

[hadley]

Hmmm, let's think about this a bit more from first principles. It seems reasonable for repeated invocations of floor or ceiling to always return the same value, i.e. ceiling(ceiling(x)) = ceiling(x) should always be true.

change_on_boundary = TRUE breaks that principle so that repeated invocation will always increment (after the first call, they'll always increment by unit. So maybe the key difference is >= vs >: change_on_boundary = TRUE will always generate a value that is greater than the current value.

So I think this does come down to the side of the interval that's closed. Ceiling is usually defined as min(n in Z, n >= x), but when change_on_boundary = TRUE it's defined as min(n in Z, n > x).

[hadley]

Oh that's just floor(x) + 1. So I think that implies that ceiling_date(x, unit, TRUE) == floor(date, unit ) + unit(1).

In which case does it even need to be an option?

[hadley]

That would also fix the lack of symmetry with floor_date().

So I'd recommend deprecating change_on_boundary() - keep the current behaviour for now, but warn suggesting floor + 1, and then remove in the next release.

[vspinu]

Oh that's just floor(x) + 1. So I think that implies that ceiling_date(x, unit, TRUE) == floor(date, unit ) + unit(1).

Hmm. I wonder why didn't this occur to me :/. I was always computing it from the first principles. Deprecation seems to be the right way to go. Some efficiency will be lost but that's not a big deal.

[vspinu]

There is an inconvenience in this approach. First, not all ceiling units have a constructor counterpart ("bimonth", "halfyear"). Second, with multi-unit rounding you would need something like floor_date(x, "2months") + months(2) which is not so nice if you have to do it programatically.

I am also doubting the readability of the code. For a person who is not aware of the boundary issue, this code might not be at all clear.

[hadley]

Well, the insight should at least make it easier to implement, and I think it argues that closed is an appropriate argument name. (And now "bimonth" and "halfyear" could be trivially transformed to "2 months" and "6 months") (Which makes me wonder if we should support periods directly, i.e. ceiling_data(x, months(2))).

However, it's not clear to me that this is such a common operation that lubridate needs to bend over backwards to make it happen, and I wonder if forcing people to realise this is a floor + increment might improve their mental model of the underlying data manipulation.

[vspinu]

Which makes me wonder if we should support periods directly, i.e. ceiling_data(x, months(2))

I think this makes sense and is very much related to #459. There is no reason to stick to multiples of a unit either; one should be able to do floor_date(x, "1m 30s") just as well.

However, it's not clear to me that this is such a common operation that lubridate needs to bend over backwards to make it happen,

The use case is primarily for units that don't have natural 0 - months, weeks and multi-days. If your observation is on Monday, you would probably want to shift it towards next Monday together with all other observations within that week. Not changing on boundary rarely makes sense for weeks and months.

and I think it argues that closed is an appropriate argument name.

I don't see why that would be. "closed" is a shortcut for "closed_restriction", "open" is for "open_restriction", "change" is for "change_on_boundary".

I think your chain of thought starts with the ceiling formula as ceiling(x)=min(n \in Z, n > x) where Z is a set of boundary points. While correct, that formula would need a thousand words to be explained. You need to define (Z) set of boundary points, (R) set of all points, (n> x) set of restricted points, and then take a min over the intersection of Z and the restricted set. That seems like an excursion into topology not a user friendly explanation of a simple concept.

Note that open/closed in this definition refers to the restriction that starts with x. So it's not "close_boundary" of the unit interval. I think people tend to think of a unit intervals between two boundary points when they think about floor/ceiling, and not about closed/open interval that starts with x. This is why I believe that our parameter should refer to the interval boundary. If we call it "closed" people would think about "closed-boundary-of-the-unit-interval", but that doesn't make much sense.