Timestamps: proper support for temporal maps (client-side)

[davidmanzanares]

Right now the only supported data types are numbers and categories in the form of strings.

We need to support timestamps and give the proper Date/Time utils to work with them.

The WWI_Ships example is a good starting point since it is working thanks to a column which is the number of days since 1917 instead of using the timestamp column.

We need to define the syntax/style API first.

I imagine something like:
torque($date, from: '15/01/1917', to: '1/01/1922', speed: '15 days'/'1 second', range: '10 days', trail: '10 days')

Where from and to are the start and end timestamps (should be optional, by default it should take the minimum and maximum timestamps of the dataset),
speed is the simulated time that passes each real-time second of the simulation, in this case 15 days per second,
range is the time duration in which the input is considered active (i.e. temporalSimulation returns 1),
trail is the time duration in which the input is considered semiactive (i.e. temporalSimulation returns a number greater than 0 and less than 1).

The output of this function is (regarding the input $date) is:

Output
 ^
|1.66|
|1.33|
|1.0 |        ______
|0.66|       /      \
|0.33|      /        \
|0.0 | ____/          \____
=================================> Time

Note:
I've used named arguments, IMO this improves clarity, but we haven't implemented this yet.

[davidmanzanares]

After talking with @rochoa and discarding the named parameters example because adding it would difficult the consistency between JS API and String API. We came to the following examples:

s.torque(s.prop('d'), 10);
s.torque(s.prop('d'), 10, s.fade(0.1, 0.6), s.dateRange('15/01/1917', '1/01/1922'));
s.torque(s.prop('d'), 10, s.default, s.dateRange('15/01/1917', '1/01/1922'));

EDIT: Not applicable anymore:

This would require:

- [ ] Adding `torque(property, durationInSeconds=10, fade=s.default, range=s.default)` which is similar to the already implemented `near()`, but it has better semantics and is more controllable (see `fade()`).
- [ ] Adding `s.DEFAULT` as a symbolic constant for default parameters, it would be accessed with just `default` in the string API.
- [ ] Adding `fade(arg1, arg2=s.default)`, which will have the following semantics: with one parameter, it will set fadeIn and fadeOut to that parameter, when called with two parameters, fadeIn and fadeOut will be assigned to them respectively.
- [ ] Adding `dateRange(from, to)`, which will parse `from` and `to` to get date timestamps.
- [ ] Adding `globalDateRange(property)` which will be used by `torque()` when range is set to default.

Related to: #130

[davidmanzanares]

After talking, again, with @rochoa, we came to the conclusion that the dateRange should be part of the first argument, which is similar to ramp(linear....

Examples:

Default min/max:
filter:       torque($day, 40, fade(0.1, 0.3))`

Explicit min/max:
filter:       torque(linear($day, '15/01/1917', '1/01/1922'), 40, fade(0.1, 0.3))`

[davidmanzanares]

• Add torque()
• Add fade()
• Get default min/max timestamps
• Add support for literal timestamps: '15/01/1917'
• Add support for ´linear´ with timestamps

[rochoa]

Literal timestamps should follow ISO 8601, as it would be easier to support time zones and adjusting that to the client configuration.

[davidmanzanares]

@rochoa I guess this https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse is not good enough, from their docs:

Note: parsing of date strings with the Date constructor (and Date.parse, they are equivalent) is strongly discouraged due to browser differences and inconsistencies. Support for RFC 2822 format strings is by convention only. Support for ISO 8601 formats differs in that date-only strings (e.g. "1970-01-01") are treated as UTC, not local.

Do you recommend some library?

[rochoa]

My recommendation is Moment.js, but for the time being, we can rely on the constructor and assume it will work in modern browsers (the browsers we support in the library). See:

> new Date('2018-03-06T17:00:00.000Z')
< 'Tue Mar 06 2018 18:00:00 GMT+0100 (CET)'

[IagoLast]

Moment.js is quite heavy, I think date constructor will do the job.

[Jesus89]

I replaced moment.js by little maths with Date some time ago, saving half size of the Carto.js bundle: CartoDB/carto.js#1981

[davidmanzanares]

Implemented with Date constructor