Timeseries ML Specifications

Timeseries ML is a specification to describe timeseries data which is assumed to be used in insilico ML models. (See timeseires-set in ISML)

insilico-timeseries is a top-tag of the timeseriesML (TSML). The insilico-timeseries has the following children; unit-set, timeseries-data-set.

In the unit-set, we define the units which are used in timeseries data. And the timeseries-data-set has a set of timeseries data which are the main elements of TSML.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<is-ts:insilico-timeseries xmlns:is-ts="http://www.physiome.jp/ns/insilicoml/timeseriesml" >
 
  <is-ts:unit-set>
    ... children of unit-set
  </is-ts:unit-set>
 
  <is-ts:timeseries-data-set>
    ... childeren of timeseries-data-set
  </is-ts:timeseries-data-set>
 
</is-ts:insilico-timeseries>

All units used in the TSML must be defined in this section. The description method of this section is same with the section of “unit-set” in ISML.

The timeseries-data-set consists of one property and some timeseries-data. In the property, miscellaneous information of the timeseries data is described.

<is-ts:timeseries-data-set>
 
  <is-ts:property>
    ... children of property
  </is-ts:property>
 
  <is-ts:timeseries-data>
    ... children of timeseries-data
  </is-ts:timeseries-data>
 
</is-ts:timeseries-data-set>

In property section, the miscellaneous information of time-series data is described. This includes following tags; name, article-set, creator-set, and description.

<is-ts:timeseries-data-set>
 
  <is-ts:property>
    ... children of property
  </is-ts:property>
 
  <is-ts:timeseries-data>
    ... children of timeseries-data
  </is-ts:timeseries-data>
 
</is-ts:timeseries-data-set>

This describes name of time-series data set. The format of the contents can be free-text.

This is a top tag including several article tags. The description method of this section is same with the section of “article-set” in ISML.

This is a top tag including several creator tags. The description method of this section is same with the section of “creator-set” in ISML.

This is free text to explain what time-series data is.

<is-ts:description> can be long sentence </is-ts:description>

The timeseries-data consists of three elements; data, property, and referenced-by. data and property describe time-series data information. referenced-by explains about models which use the time-series data. A timeseries-data has a timeseries-id which is written as UUID.

<is-ts:timeseries-data>
 
  <is-ts:data>
    ... data
  </is-ts:data>
 
  <is-ts:property>
    ... children of property
  </is-ts:property>
 
  <is-ts:referenced-by>
    ... children of referenced-by
  </is-ts:referenced-by>
 
</is-ts:timeseries-data>

The data describes timeseries data. There are three types about timeseries data; scalar, vector, and matrix. The type is described in “timeseries-data property dimension”.

How to read each type data is as follows.

scalar

The scalar type data is described from start time to end time in sequence with a single space separation.

<is-ts:data>
  x(t_1) x(t_2) ... x(t_i-1) x(t_i)
</is-ts:data>

vector

The vector type data is described from start time to end time in sequence with a single space separation. All elements of vector at each time are described together as a set.

<is-ts:data>
  V_1(t_0) V_2(t_0) V_3(t_0) V_1(t_1) V_2(t_1) V_3(t_1) ... V_1(t_i) V_2(t_i) V_3(t_i)
</is-ts:data>

matrix

The matrix type data is described from start time to end time in sequence with a single space separation. All elements of matrix at each time are described together as a set. Numbers of elements are defined as follows.

There is an m-n matrix (column amount is m, row amount is n) An element whose column number is i, and row number is j is calculated as

<is-ts:data>
  m_1(t_0) m_2(t_0) m_3(t_0) m_4(t_0) m_5(t_0) m_6(t_0)
  ...
  m_1(t_i) m_2(t_i) m_3(t_i) m_4(t_i) m_5(t_i) m_6(t_i)
</is-ts:data>

The name of time-series data, element-information-set, and information about acquisition-method, dimension, and sampling, are described in this section.

<is-ts:property>
 
  <is-ts:name> name of time-series data </is-ts:name>
 
  <is-ts:acquisition-method>
    ... children of acquisition-method
  </is-ts:acquisition-method>
 
  <is-ts:dimension>
    ... children of dimension
  </is-ts:dimension>
 
  <is-ts:element-information-set>
    ... children of element-information-set
  </is-ts:element-information-set>
 
  <is-ts:sampling>
    ... children of sampling
  </is-ts:sampling>
 
</is-ts:property>

name of timeseries data is described in here.

<is-ts:name> name of time-series data </is-ts:name>

acquisition-method of timeseries data. This section has an attribute; type which will have value experiment or simulation. Additionally, acquisition-method has a child element; description, to describe further information of acquisition method.

<is-ts:acquisition-method type="experiment">
  <is-ts:description>
    ... details about how to experiment.
  </is-ts:description>
</is-ts:acquisition-method>

<is-ts:acquisition-method type="simulation">
  <is-ts:description>
    ... details about how to simulate.
  </is-ts:description>
</is-ts:acquisition-method>

dimension of timeseries data. dimension has an attribute; type which will have value scalar, vector, or matrix. When the type is scalar, dimension does not have any child tag. When dimension whose type is vector or matrix, there are children tags; col, row.

<is-ts:dimension type="scalar"/>

<is-ts:dimension type="vector">
  <is-ts:col>3</is-ts:col>
</is-ts:dimension>

<is-ts:dimension type="matrix">
  <is-ts:col>2</is-ts:col>
  <is-ts:raw>3</is-ts:raw>
</is-ts:dimension>

Further information of element of time-series data is described in this section. element-information-set can have multiple children element tags.

<is-ts:element-information-set>
  <is-ts:element>
    ... children of element
  </is-ts:element>
</is-ts:element-information-set>

element describes a further information about the element of timeseries data. The element is specified by using number of column, and row. These elements are numbered by element-id, which is unique in a timeseries-data. element has several other attribute; unit-id and precision, and has child tag; name and description.

When there are no descriptions about column or row, the attribute have a default value “1”.

<is-ts:element element-id="1" unit-id="9" precision="double" col="2" row="3">
  <is-ts:name> name of element </is-ts:name>
  <is-ts:description> description of sub-matrix </is-ts:description>
</is-ts:element>

Additionally, vector or sub-matrix can be specified by using ”: (colon)” expression as follows.

<is-ts:element element-id="1" unit-id="9" precision="double" col="2:3" row="3:5">
  <is-ts:name> name of sub-matrix </is-ts:name>
  <is-ts:description> description of sub-matrix </is-ts:description>
</is-ts:element>

The sampling describes the information of time axis of the timeseries data, e.g. sampling interval. sampling has two attribute; unit-id and type. unit-id explain about unit of time. type will have value constant-step or variable-step.

When the type of sampling has a value of constant-step, sampling has two children elements; start-time and step. And when the type has a value of variable-step, sampling has one child element; time-axis.

<is-ts:sampling unit-id="3" type="constant-step">
  <is-ts:start-time>0.0</is-ts:start-time>
  <is-ts:step>0.001</is-ts:step>
</is-ts:sampling>

<is-ts:sampling unit-id="3" type="variable-step">
  <is-ts:time-axis>
    ... value of time-axis
  </is-ts:time-axis>
</is-ts:sampling>

start-time

Start time of the time-series data.

step

Sampling step of the time-series data.

time-axis

Time axis of the timeseries data. Amount of element of time-axis must be same with the amount of timeseries data (when the type of timeseries data is vector or matrix, the amount of timeseries data must be same with the product of the amount of time-axis elements and the amount of vector elements or matrix elements)

<is-ts:sampling unit-id="3" type="variable-step">
  <is-ts:time-axis>
    0.001 0.003 0.004 0.007 ... 99.9998 100.00
  </is-ts:time-axis>
</is-ts:sampling>

In this section, relationships between insilicoML (ISML) and TSML are described. referenced-by has a child tag; model-set.

<is-ts:referenced-by>
  <is-ts:model-set>
    ... children of model-set
  </is-ts:model-set>
</is-ts:referenced-by>

model-set consists of a number of model tags. If the target model has db-id (i.e. the model has already been registered into insilicoDB), model has db-id tag as a child element. Otherwise, model has model-name tag to describe the name of the model.

<is-ts:model-set>
  <is-ts:model>
    <is-ts:model-name> Name of model </is-ts:model-name>
  </is-ts:model>
</is-ts:model-set>
<is-ts:model-set>
  <is-ts:model>
    <is-ts:db-id> db-id of model </is-ts:db-id>
  </is-ts:model>
</is-ts:model-set>