Calculating Time Spans

In this guide we will take a look at calculating start and end times for analysis queries.

Selecting start and end times

When submitting analysis queries it's important that you consider the start and end parameters you use. You'll often want to select a time period such as a day for your query and submit many queries for this same period.

Note that although start and end times are optional we recommend you specify these parameters for every query you submit so that you understand exactly what time period you are analyzing. If no start and end times are used, the platform defaults to the past 24 hours.

The PYLON platform assumes time starts at the UNIX Epoch (Midnight, 1st January 1970 UTC). Each interval starts at the epoch and boundaries between intervals are maintained from the epoch.

Note: Start times are inclusive and end times are exclusive.

To ensure results from all periods are comparable, Analysis Query start and end times should be selected to include whole periods of data.

For example, when using an hourly interval if you specify the start of the Analysis Query as 09:30, then the first result only contains the interactions until the boundary of the next period (10:00:00). This can be confusing as you'd be comparing counts for one interval of 30 mins with other intervals of one hour.

For time series analysis, when using a span greater than one to increase the period duration, keeping to period boundaries becomes even more important. The following diagram shows how all periods are calculated from the epoch when you use a span value of 3.

It is important that your start and end times align with the period boundaries, otherwise some intervals of the analysis will contain less than 3 hours of data.

Calculating Time Periods

Calculating Start Times

The following steps are used to calculate a start time which is on the period boundary after a desired time.

  • Calculate period duration in seconds

    • Multiply the interval in seconds by the span
    • This example shows an hourly interval with a span of three.
    • seconds in a minute x minutes in a hour x span
    • 60 x 60 x 3 = 10800 seconds
  • Calculate the desired Query Analysis start time in seconds from the epoch

    • Use your chosen programming language or a site such as http://www.epochconverter.com/ to perform the conversion
    • Human time 2015-03-06 12:50:00 UTC = Epoch timestamp: 1425646200
  • Find the number of periods since the epoch up to the desired start time

    • number of seconds since the epoch / seconds in a period
    • 1425646200 / 10800 = 132004.2781
  • Calculate the number of periods between the epoch and the end of the period which contains the desired start time.

    • round up number of periods
    • roundup(132004.2781) = 132005
  • Calculate the start of the period as number of seconds from the epoch
    • number of periods x seconds in a period
    • 132005 x 10800 = 1425654000

Use the result as a start time in the Analysis Query. In human readable form, the new start time is 2015-03-06 15:00:00.

 start = 1425654000

Calculating End Times

The following steps are used to calculate an end time which is on the period boundary before a desired time.

  • Calculate period duration in seconds

    • Multiply the interval in seconds by the span. The example shows an hourly interval with a span of three.
    • seconds in a minute x minutes in a hour x span
    • 60 x 60 x 3 = 10800 seconds
  • Calculate the desired Analysis Query end time in seconds from the epoch

    • Use your chosen programming language or a site such as http://www.epochconverter.com/ to perform the conversion
    • Human time 2015-03-09 22:53:00 UTC = Epoch timestamp: 1425941580
  • Find the number of periods since the epoch up to the desired end time

    • number of seconds since the epoc / seconds in a period
    • 1425941580 / 10800 = 132031.6277777778
  • Calculate the number of periods between the epoch and the start of the period which contains the desired end time.

    • round down number of periods
    • rounddown(132031.6277777778) = 132031
  • Calculate the end of the period as number of seconds from the epoch

    • number of periods x seconds in a period
    • 132031 x 10800 = 1425934800

Use the result as an end time in the Analysis Query. In human readable form, the new end time is 2015-03-09 21:00:00.

 start = 1425654000
 end = 1425934800