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 start and end times are optional and use a standard UNIX timestamp. 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.

epoc

In this example, a recording was started at 2015-01-01 09:30:00 and stopped at 2015-01-01 17:30:00.

recording

When using an hourly interval, if the start of the Analysis Query was at the start of the recording (09:30:00), 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 comapring counts for one interval of 30 mins with other intervals of one hour.

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

Start the analysis at the first period boundary after the recording starts and end the analysis at the last period boundary before the recording ends. In the case of an hourly recording, the Analysis Query should start at the next full hour after the recording starts and end on a full hour before the end of the recording.

snap-span1

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

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.

periods

The start and end times for an Analysis Query must now be calculated to hit the boundaries of the periods. In this example, the recording starts 90 minutes before the start of the next full period of data and ends 30 minutes after the last full period of data.

new%20period%20mapping%201

The Analysis Query should only include the two periods which have complete data.

new%20period%20mapping%203

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_time = 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_time = 1425654000

 end_time = 1425934800