# Missing values¶

A time series essentially produces a sequence of values associated to equality spaced points in time. However, in practice, some values may be missing, because the measured values do not exist before or after a given date. When simulating the measure of a phenomenon, one could also desire to simulate the fact that the simulated sensor misses a measure, so that ‘holes’ appear in the time series.

The generator presented in this document support missing values by generating time series that can associate undefined value to any submitted timestamp. Composite time series take into account the fact that the baseline time series may produce such undefined values in a conservative way: a transformation time series produce an undefined value if its baseline time series produces an undefined value. The transformation applied may transform a defined value into an undefined one.

Aggregation time series discard all the undefined values produced by the baseline time series, so that the aggregation only applies on defined values. If no defined values are produced by the underlying time series, an undefined value is retrieved, regardless the aggregation function used on the time series.

While any time series can produce undefined values, some of them are specifically designed to transform
a defined value into an undefined one, and *vice versa*.

## Undefined time series¶

This time series always produces undefined values.

**Representation in the configuration document:**

- name
- The name given to the generator describing a time series. This name must be unique among all generators in the configuration document.
- type
- Mandatory. Must be “undefined”.

**Example**:

```
{
"name": "undefined-generator",
"type": "undefined"
}
```

## Limited Time Series¶

This time series removes the values generated by a baseline time series and replaces them by missing values.

**Representation in the configuration document:**

- name
- The name given to the generator describing a time series. This name must be unique among all generators in the configuration document.
- type
- Mandatory. Must be “limited”.
- generator
- Mandatory. The generator describing the baseline time series.
- from
- Optional. Specifies the date before which the time series must not produce any value. By default, there is no limit date and no values are generated before the higher limit.
- to
- Optional. Specifies the date at which the time series must start to generate values again. By default, there is no limit date and no values are generated after the lower limit. If neither the lower nor the higher limit are specified, the time series will generate no values.

**Example**:

```
{
"name": "limited-generator",
"type": "limited",
"generator": "daily-generator",
"from": "2016-01-01 00:00:00.000",
"to": "2016-04-23 00:00:00.000"
}
```

## Partial Time Series¶

Instead of specifying the periods during which a time series must not generate any values, one can specify the periods during which the time series must generate these values.

This transformation time series is the complement of the limited time series.

**Representation in the configuration document:**

- name
- The name given to the generator describing a time series. This name must be unique among all generators in the configuration document.
- type
- Mandatory. Must be “partial”.
- generator
- Mandatory. The generator describing the baseline time series.
- from
- Optional. If specified, indicates the date from which the values generates by the baseline time series must by generated. By default, there is no lower limit, and values must be generated until the higher limit.
- to
- Optional. If specified, indicates the date to which the values generated by the baseline time series must be generated. By default, there is no higher limit, and values must be generated from the lower limit.
- missing-rate
- Optional. Must be a number between 0 and 1. If specified, indicates the probability that a generated value will be considered as missing, despite the fact that the lower and higher time constraints are verified. A value of 0 means that no value will be missed ; a value of 1 means that all the values will be missed. By default, this parameter is set to 0.

**Example**:

```
{
"name": "partial-generator",
"type": "partial",
"generator": "daily-generator",
"from": "2016-01-01 00:00:00.000",
"to": "2016-04-23 00:00:00.000",
"missing-rate": 0.001
}
```

## Default Time Series¶

A common behavior time series pattern consists in retrieving the first defined value among those produced by multiple time series. The default time series is based on an ordered list of baseline time series, and produces the first defined value of these time series.

If the values of all time series are undefined, an undefined value is produced.

**Representation in the configuration document:**

- name
- type
- Mandatory. Must be ‘first-of’.
- generators
- Mandatory. A list of generators describing the baseline time series.

**Example**:

```
{
"name": "default-generator",
"type": "first-of",
"generators": ["daily-generator", "random-generator"]
}
```