torque/doc/torque_time_slider.md

Torque Time Slider

You can use the time_slider option to show an animated time slider with Torque layers. This option is enabled by default when creating visualizations with cartodb.createVis and createLayer. Both require a map_id DOM object.

Enable / Disable the Torque Time Slider

Description | The Torque time slider is enabled by default, for your visualization or layer. Sample Torque.js Code | { time_slider: true }); Default Value | true, enabled by default. Available Values | See boolean. Related Examples | To disable the time slider option, use time_slider: false. See No Torque Time Slider - Example Code.

For a code example about how to use the time_slider option to modify a Torque map, see Torque with a Custom Time Slider.

Note: The time_slider option is specific for Torque.js only. All the other CARTO.js options are also supported for Torque.js. For the complete list of arguments, options, and returns, see CARTO.js API Methods.

Customize Animation for your Time Slider

You can customize the animation of your Torque time slider by editing the -torque-frame-count and -torque-animation-duration CartoCSS properties. (Optionally, you can create a CARTO.js map to create a custom time slider). This section also describes how time interval data is aggregated, and describes the formula used to calculate time buckets.

• -torque-frame-count specifies the number of animation steps/frames in your torque animation. You can change the time slider timestamp by adjusting the number of steps.
  
  Tip: In CARTO Builder, this is the STEPS value when the style is ANIMATED.

• -torque-animation-duration specifies the length of time for your animation, in seconds. You can adjust the duration of the animation as needed.
  
  Tip: In CARTO Builder, this is the DURATION value when the style is ANIMATED.

Aggregating Time Interval Data

Before customizing the time slider, you should understand how Torque time interval data is calculated. Torque aggregates time (rather than use an exact start time and end from your column fields). Torque calculates the time interval as follows:

• Reads the first date/time stamp from your dataset
• Reads the last date/time stamp to from your dataset
• Aggregates the time period based on the first and last date/time stamp (including seconds)
• Once the time interval is defined, it breaks the time period up in smaller "buckets"
• The number of buckets is based on the number of Steps you select for your Torque map
• Each bucket, or step, is one animation frame

Thus, the start and end time for each bucket depends on the number of divided steps (not a specific start time or end time that you entered).

Note: If you are creating Torque maps with CARTO Builder, the date format of the Torque time slider is automatically calculated by CARTO and cannot be edited. See Calculating the Time Slider in CARTO Builder for more details.

Formula for Calculating Time Buckets

The following formula can help you calculate the number of steps for your Torque data.

time = times.start + (times.end - times.start)*(step/total_steps);

Where:

• time = time at each hop
• times.start = the earliest time in your date/time column
• times.end = the latest time in your date/time column

The Torque time slider displays these buckets of time, animating the entire sequence of your dataset, and divides the time according to the number of specified steps. You can alter the duration of the animation, and adjust the time slider timestamp with the number of Steps.

Calculating the Time Slider in CARTO Builder

When creating Torque maps with CARTO Builder, the date format of the Torque time slider is automatically calculated by CARTO, depending on the range of time in your dataset. It cannot be edited. If your data contains the following range of time, the time slider displays as described:

• Time range is less than one day, the time slider displays the time
• Time range is less than three days, the time slider displays the day and time
• Time range is more than three days, but less than a year, the time slider displays the month/day/year
• Time range is more than a year, the time slider displays the month/year