Overview

d2xlab is a software for exploring time series of floating point data. It includes features for importing, editing, visualizing and exporting time series.

d2xlab time series model assumes a fixed time step between samples. This constraint is usually statisfied for time series produced by numerical simulations or recorded from sensors. That enables some interesting editing features like combining different data using mathematical expressions, or using fft-based filtering.

d2xlab can be useful in various engineering fields such as mechanical engineering, environmental engineering, structural dynamics…

Basic concepts

A series is the primary building block. It represents a single time series. Several series can be gathered into a bag. All series from a bag share the same time vector.

A series can be static, which means that its values are defined by an array of floating point values, or dynamic, meaning that its values are defined by a mathematical expression.

A variable is a floating point value that can be referenced in mathematical expression of dynamic series.

Automatic calculation

The application maintains a graph connecting parent series or variables to dynamic series. When a series or variables is changed, the graph is used to automatically recalculate any dynamic series that depends on it, like a spreadsheet program whould do when changing the value of one cell.

Importing data

d2xlab can import data from text files located on your local computer or from a text buffer when using the clipboard (not available in older Firefox versions).

Data Format

The data format is text based. UTF-8 encoding is assumed.

By default, d2xlab will attempt to infer the format of the data. When loading a file from the disk, a dialog will open and presents the parsing options that has been inferred. These options can be changed before actually loading the file to suit a particular format.

General layout

Data shall be laid-out column wise: one or more columns shall provide time information; other columns provide the value of the series to be read. Values shall be separated by a separator that shall be the same troughout the file. The separator can be a single or multiple space, comma, semi-colum or a tabulation.

Example with a bag containing 2 series of 4 samples each:


            Time,  A, B
             0.1,  0, 2
             0.2,  1, 1
             0.3,  1, 7
             0.4,  9, 1

Headers

A header line shall contain the name of each series. If no header line is present, the application will assume that the first column of the data describes the time.

By default, a column with time as a header (the case does not matter) will be sought and used as the time column.

Series names shall obey to following rules: only alphanumeric character are allowed, with _ as an exeption and the name can not start with a digit.

Names inferred from headers will be mangled such as to conform to the above rules by replacing any forbidden characters by _.

Comments

By defaut, any text in a row after // will not be parsed. In addition, any text above the header line will be ignored.

Numbers

Numbers shall use the dot as decimal separator.

Time Vector

This application is aimed at working with time series that have a fixed time step. When importing data, if that constraint is not satisfied, a time step will be inferred (either the most frequent one or an average one) and re-interpolation will be made.

Time values shall be obvioulsy strictly increasing. Time values can be either a floating point, interpreted as a time point in second, or a datetime.

Skip Columns

You can specify indexes of columns to be skipped (0-based, comma separated). If left blank, the parser will parse all columns.

Parsing datetime

The automatic parser will recognize ISO datetime format, for example 2011-04-12T12:00:00. More complex datetime format can be handled by specifying the name of the columns to be used, separated by commas and a time format string (including the commas when relevant).

For example datetime for the following bag can be parsed using Year,Month,Day,Hour,Min as columns names, and yyyy,MM,dd,HH,mm as time format string:


             Year Month Day Hour Min   A    B
             2017    02  05   13  56 0.3 0.98
             2017    02  05   13  57 0.3 0.98
             2017    02  05   13  58 0.3 0.94
             2017    02  05   13  59 0.2 0.98

Possible format specifiers are provided below.

Token	Description	Example
`S`	millisecond, no padding	`54`
`SSS`	millisecond, padded to 3	`054`
`u`	fractional seconds, functionally identical to SSS	`054`
`uu`	fractional seconds, between 0 and 99, padded to 2	`05`
`uuu`	fractional seconds, between 0 and 9	`0`
`s`	second, no padding	`4`
`ss`	second, padded to 2 padding	`04`
`m`	minute, no padding	`7`
`mm`	minute, padded to 2	`07`
`h`	hour in 12-hour time, no padding	`1`
`hh`	hour in 12-hour time, padded to 2	`01`
`H`	hour in 24-hour time, no padding	`9`
`HH`	hour in 24-hour time, padded to 2	`13`
`Z`	narrow offset	`+5`
`ZZ`	short offset	`+05:00`
`ZZZ`	techie offset	`+0500`
`a`	meridiem	`AM`
`d`	day of the month, no padding	`6`
`dd`	day of the month, padded to 2	`06`
`M`	month as an unpadded number	`8`
`MM`	month as a padded number	`08`
`MMM`	month as an abbreviated localized string	`Aug`
`MMMM`	month as an unabbreviated localized string	`August`
`y`	year, unpadded	`2014`
`yy`	two-digit year	`14`
`yyyy`	four- to six- digit year, pads to 4	`2014`
`'`	literal start/end, characters between are not tokenized	`T`

If the timezone is not specified by the datetime, the data will be assumed UTC encoded. This can be changed in the parsing options. IANA style (example:'America/New_York') or fixed offset (example: UTC+1) are accepted.

In anycase, datetime will be converted to the local time.

Visualizing Data

To display a series, double click on its name in the tree view. You can turn on several series and display them together.

Tree View

Plots type can be changed by clicking on the menu above the figure.

Changing plot type

You can pop up addtionnal actions by a right click on a series name.

Creating Series

Series are created using one of the options available at the bottom of the tree view.

Selecting several series (SHIFT or CTRL + left click) unlock additional options.

Create a Series

The mathematical expressions defining the series can be edited in the Calculator panel.

Calculator

The syntax is inspired by python / numpy as described here after.

Operators

The following basic operators are supported.

Operator	Description
`+`	addition
`-`	substraction
`*`	multiplication
`/`	floating point division
`**`	power
`[]`	value access (zero based)

Example: (2 * Fx - Fy[0]**4) / A

Boolean operators

Boolean operations are also supported. True/false are cast to floating point values 1.0 and 0.0 This is especially usefull for doing conditional expression.

Operator	Description
`>`	greater than
`<`	lower than
`>=`	greater or equal than
`<=`	lower or equal than
`==`	equal
`!=`	not equal

Example: (Fx > Fy) * B + (Fx <= Fy) * C

Supported functions

The engine supports also a wide range of mathematical functions.

Function name	Description
`sin`	sinus
`cos`	cosinus
`tan`	tangent
`asin`	arc sinus
`acos`	arc cosinus
`atan`	arc tangent
`sinh`	sinus hyperbolic
`cosh`	cosinus hyperbolic
`tanh`	tangent hyperbolic
`asinh`	arc sinus hyperbolic
`acosh`	arc cosinus hyperbolic
`atanh`	arc tangent hyperbolic
`exp`	exponential
`log`	natural logarithm
`log10`	logarithm base 10
`sqrt`	square root
`abs`	absolute value
`pow`	power
`cumsum`	cumulative vector sum
`diff`	difference between consecutive array elements (zero padded)
`degrees`	convert angles from radians to degrees
`radians`	convert angles from degrees to radians
`sum`	sum of the vector elements
`average`	average of the vector elements
`min`	minimum value of the vector elements
`max`	maximum value of the vector elements
`std`	standard devation of the vector elements

Example: sin(radians(theta + 45)) * max(Fx)

Built-in vector & variables

The following variables are built-in and can be used in expressions:

pi the value of π
fs the sampling frequency (in Hz) of the series

In addition, the time vector of the series can be accessed using time. You can play with the demo which makes use of some of the above built-in.

Exporting data

Bag can be exported to csv format and dowloaded. The exported data represents a snasphot of the current state of the Bag, meaning that time control and online filters are accounted for.