How to :: manage your dates format

Overview

You will often have to play with dates in your Toucan application and there are a few tips you need to know to become a Toucan date master ! 📅

There are 2 steps you will likely use to display dates in your charts:

  • in the dataset editor : make sure your date column is properly interpreted
  • in the configuration of your graph : decide how you want the date to be displayed

Define a date column

You need to make sure your date column is properly interpreted

This step is mandatory if you are using a date column in your charts : it will allow Toucan to interpret your date column in your data as a date (an not simply a number or a string)

This parameter needs to be define in the Dataset Editor menu.

date:
  selector:"your_date_column"
  format:"format_of_your_date_column" #ex: %Y for the year

The format is how your date looks like in your data today. You describe here how the date is written in your data.

Note

The format of your date column has to be written using the following syntax : https://github.com/d3/d3-time-format#api-reference

You can define date format on multiple columns, just like below :

datasets:
  my_dataset:
    id: "my_dataset"
    query:
      domain: "timeline"
    date: [
      {
        selector: "start_date"
        format: "%Y-%m-%d %H:%M:%S"
      }
      {
        selector: "end_date"
        format: "%Y-%m-%d %H:%M:%S"
      }
    ]

Use date parameters

Once Toucan understands your column is a date column, you can apply date parameters. This will allow you to modify how the date is displayed for your end-users for example.

Charts parameters

You might want to change the way dates are displayed by default in your charts. In order to do just that, our linechart, particularly well-suited to display dates, has a built-in options that will allow you to manage dates. It’s called the ticks parameters.

In your optional parameters, you will be able to setup :

Image of chart options

Image of chart options

  • X Ticks Format (tickformat in code mode) : write here the format you wish to be displayed according to the same syntax we saw previously (ex: “%Y”)
  • Hide Start and End Ticks (hideXTickLimits in code mode) : turn on this option to hide the first and last tick
  • Display all X Ticks (displayAllXTicks in code mode) : by default, Toucan displays a certain amount of ticks according to design rules. If you wish all you ticks, turn on that option

Two other options only available in code mode for the linechart are :

  • dateFormat : write down the date format you wish to display in the legend
  • selectLastDate : turn on that option to always display first the last date available

Note

For the barchart, stackedbarchart and the barlinechart, the tickformat parameter is also available in code mode. Check their reference pages :

Postprocess

If your chart does not have a tickformat parameter and you need to modify how it’s diplayed, no worries ! We have a postprocess function to help you out :

Check out our change_date_format function.

Just define the output format you want!

Filters / Requesters

The filter slider or a requester is especially recommended to display dates. It has specific options you can use with dates :

  • some date format parameters
  • you can put the ‘default’ parameter on “last” to set it on the last date by default
  • you can order it on specific column

Order dates

If your dates need to be ordered, use the order option of your graph like labelsOrder or groupsOrder for example.

Make sure the date is either displayed in the following format:

  • Year - month

or

  • Month - day

Why ? Because the order column sorts ascendingly and that way dates will be properly sorted. Ex: 201801 will be before 201802

Other cool dates stuff

  • Date is one of the 2 most structuring variable you can define in a Toucan App : learn how to build the best date selector
  • You can add aggregation columns based on the date : check out these postprocess functions
  • compute_cumsum : to compute to date values;
  • compute_evolution_by_frequency : to compute evolution values