---
# System prepended metadata

title: Time Series Software Standards
tags: [statistical-software]

---

---
title: Time Series Software Standards
tags: statistical-software
robots: noindex, nofollow
---


<!-- Edit the .Rmd not the .md file -->

## Time Series Software

The category of Time Series software is arguably easier to define that
the preceding categories, and represents any software the primary input
of which is intended to be temporally structured data. Importantly,
while “*temporally structured*” may often imply temporally ordered, this
need not necessarily be the case. The primary definition of temporally
structured data is that they possess some kind of index which can be
used to extract temporal relationships.

Time series software is presumed to perform one or more of the following
steps:

1.  Accept and validate input data
2.  Apply data transformation and pre-processing steps
3.  Apply one or more analytic algorithms
4.  Return the result of that algorithmic application
5.  Offer additional functionality such as printing or summarising
    return results

This document details standards for each of these steps, each prefixed
with “TS”.

### 1 Input data structures and validation

Input validation is an important software task, and an important part of
our standards. While there are many ways to approach validation, the
class systems of R offer a particularly convenient and effective means.
For Time Series Software in particular, a range of class systems have
been developed, for which we refer to the section “Time Series Classes”
in the CRAN Task view on [Time Series
Analysis"](https://cran.r-project.org/web/views/TimeSeries.html), and
the class-conversion package [`tsbox`](https://www.tsbox.help/).
Software which uses and relies on defined classes can often validate
input through affirming appropriate class(es). Software which does not
use or rely on class systems will generally need specific routines to
validate input data structures. In particular, because of the long
history of time series software in R, and the variety of class systems
for representing time series data, new time series packages should
accept as many different classes of input as possible by according with
the following standards:

-   **TS1.0** *Time Series Software should use and rely on explicit
    class systems developed for representing time series data, and
    should not permit generic, non-time-series input*

The core algorithms of time-series software are often ultimately applied
to simple vector objects, and some time series software accepts simple
vector inputs, assuming these to represent temporally sequential data.
Permitting such generic inputs nevertheless prevents any such
assumptions from being asserted or tested. Missing values pose
particular problems in this regard. A simple `na.omit()` call or similar
will shorten the length of the vector by removing any `NA` values, and
will change the explicit temporal relationship between elements. The use
of explicit classes for time series generally ensures an ability to
explicitly assert properties such as strict temporal regularity, and to
control for any deviation from expected properties.

-   **TS1.1** *Time Series Software should explicitly document the types
    and classes of input data able to be passed to each function.*
-   **TS1.2** *Time Series Software should accept input data in as many
    time series specific classes as possible.*
-   **TS1.3** *Time Series Software should implement validation routines
    to confirm that inputs are of acceptable classes (or represented in
    otherwise appropriate ways for software which does not use class
    systems).*
-   **TS1.4** *Time Series Software should implement a single
    pre-processing routine to validate input data, and to appropriately
    transform it to a single uniform type to be passed to all subsequent
    data-processing functions (the [`tsbox`
    package](https://www.tsbox.help/) provides one convenient approach
    for this).*
-   **TS1.5** *The pre-processing function described above should
    maintain all time- or date-based components or attributes of input
    data.*

For Time Series Software which relies on or implements custom classes or
types for representing time-series data, the following standards should
be adhered to:

-   **TS1.6** *The software should ensure strict ordering of the time,
    frequency, or equivalent ordering index variable.*
-   **TS1.7** *Any violations of ordering should be caught in the
    pre-processing stages of all functions.*

#### 1.1 Time Intervals and Relative Time

While most common packages and classes for time series data assume
*absolute* temporal scales such as those represented in [`POSIX`
classes](https://stat.ethz.ch/R-manual/R-devel/library/base/html/as.POSIXlt.html)
for dates or times, time series may also be quantified on *relative*
scales where the temporal index variable quantifies intervals rather
than absolute times or dates. Many analytic routines which accept time
series inputs in absolute form are also appropriately applied to
analogous data in relative form, and thus many packages should accept
time series inputs both in absolute and relative forms. Software which
can or should accept times series inputs in relative form should:

-   **TS1.8** *Accept inputs defined via the [`units`
    package](https://github.com/r-quantities/units/) for attributing SI
    units to R vectors.*
-   **TS1.9** *Where time intervals or periods may be days or months, be
    explicit about the system used to represent such, particularly
    regarding whether a calendar system is used, or whether a year is
    presumed to have 365 days, 365.2422 days, or some other value.*

### 2 Pre-processing and Variable Transformation

#### 2.1 Missing Data

One critical pre-processing step for Time Series Software is the
appropriate handling of missing data. It is convenient to distinguish
between *implicit* and *explicit* missing data. For regular time series,
explicit missing data may be represented by `NA` values, while for
irregular time series, implicit missing data may be represented by
missing rows. The difference is demonstrated in the following table.

<table>
<caption>
Missing Values
</caption>
<tbody>
<tr class="odd">
<td style="text-align: left;">
Time
</td>
<td style="text-align: left;">
value
</td>
</tr>
<tr class="even">
<td style="text-align: left;">
08:43
</td>
<td style="text-align: left;">
0.71
</td>
</tr>
<tr class="odd">
<td style="text-align: left;">
08:44
</td>
<td style="text-align: left;">
NA
</td>
</tr>
<tr class="odd">
<td style="text-align: left;">
08:45
</td>
<td style="text-align: left;">
0.28
</td>
</tr>
<tr class="odd">
<td style="text-align: left;">
08:47
</td>
<td style="text-align: left;">
0.34
</td>
</tr>
<tr class="odd">
<td style="text-align: left;">
08:48
</td>
<td style="text-align: left;">
0.07
</td>
</tr>
</tbody>
</table>

The value for 08:46 is *implicitly missing*, while the value for 08:44
is *explicitly missing*. These two forms of missingness may connote
different things, and may require different forms of pre-processing.
With this in mind, and beyond the [*General
Standards*](#general-standards) for missing data (**G2.13**–**G2.16**),
the following standards apply:

-   **TS2.0** *Time Series Software which presumes or requires regular
    data should only allow **explicit** missing values, and should issue
    appropriate diagnostic messages, potentially including errors, in
    response to any **implicit** missing values.*
-   **TS2.1** *Where possible, all functions should provide options for
    users to specify how to handle missing data, with options minimally
    including:*
    -   **TS2.1a** \*error on missing data; or.
    -   **TS2.1b** *warn or ignore missing data, and proceed to analyse
        irregular data, ensuring that results from function calls with
        regular yet missing data return identical values to submitting
        equivalent irregular data with no missing values; or*
    -   **TS2.1c** *replace missing data with appropriately imputed
        values.*

This latter standard is a modified version of *General Standard*
**G2.14**, with additional requirements via **TS2.1b**.

#### 2.2 Stationarity

Time Series Software should explicitly document assumptions or
requirements made with respect to the stationarity or otherwise of all
input data. In particular, any (sub-)functions which assume or rely on
stationarity should:

-   **TS2.2** *Consider stationarity of all relevant moments - typically
    first (mean) and second (variance) order, or otherwise document why
    such consideration may be restricted to lower orders only.*
-   **TS2.3** *Explicitly document all assumptions and/or requirements
    of stationarity*
-   **TS2.4** *Implement appropriate checks for all relevant forms of
    stationarity, and either:*
    -   **TS2.4a** *issue diagnostic messages or warnings; or*
    -   **TS2.4b** *enable or advise on appropriate transformations to
        ensure stationarity.*

The two options in the last point (TS2.4b) respectively translate to
*enabling* transformations to ensure stationarity by providing
appropriate routines, generally triggered by some function parameter, or
*advising* on appropriate transformations, for example by directing
users to additional functions able to implement appropriate
transformations.

#### 2.3 Covariance Matrices

Where covariance matrices are constructed or otherwise used within or as
input to functions, they should:

-   **TS2.5** *Incorporate a system to ensure that both row and column
    orders follow the same ordering as the underlying time series data.
    This may, for example, be done by including the `index` attribute of
    the time series data as an attribute of the covariance matrix.*
-   **TS2.6** *Where applicable, covariance matrices should also include
    specification of appropriate units.*

*General Standard* **G3.1** also applies to all Time Series Software
which constructs or uses covariance matrices.

### 3 Analytic Algorithms

Analytic algorithms are considered here to reflect the core analytic
components of Time Series Software. These may be many and varied, and we
explicitly consider only a small subset here.

#### 3.1 Forecasting

Statistical software which implements forecasting routines should:

-   **TS3.0** *Provide tests to demonstrate at least one case in which
    errors widen appropriately with forecast horizon.*
-   **TS3.1** *If possible, provide at least one test which violates
    TS3.0*
-   **TS3.2** *Document the general drivers of forecast errors or
    horizons, as demonstrated via the particular cases of TS3.0 and
    TS3.1*
-   **TS3.3** *Either:*
    -   **TS3.3a** *Document, preferable via an example, how to trim
        forecast values based on a specified error margin or equivalent;
        or*
    -   **TS3.3b** *Provide an explicit mechanism to trim forecast
        values to a specified error margin, either via an explicit
        post-processing function, or via an input parameter to a primary
        analytic function.*

### 4 Return Results

For (functions within) Time Series Software which return time series
data:

-   **TS4.0** *Return values should either:*
    -   **TS4.0a** *Be in same class as input data, for example by using
        the [`tsbox` package](https://www.tsbox.help/) to re-convert
        from standard internal format (see 1.4, above); or*
    -   **TS4.0b** *Be in a unique, preferably class-defined, format.*
-   **TS4.1** *Any units included as attributes of input data should
    also be included within return values.*
-   **TS4.2** *The type and class of all return values should be
    explicitly documented.*

For (functions within) Time Series Software which return data other than
direct series:

-   **TS4.3** *Return values should explicitly include all appropriate
    units and/or time scales*

#### 4.1 Data Transformation

Time Series Software which internally implements routines for
transforming data to achieve stationarity and which returns forecast
values should:

-   **TS4.4** *Document the effect of any such transformations on
    forecast data, including potential effects on both first- and
    second-order estimates.*
-   **TS4.5** *In decreasing order of preference, either:*
    -   **TS4.5a** *Provide explicit routines or options to
        back-transform data commensurate with original, non-stationary
        input data*
    -   **TS4.5b** *Demonstrate how data may be back-transformed to a
        form commensurate with original, non-stationary input data.*
    -   **TS4.5c** *Document associated limitations on forecast values*

#### 4.2 Forecasting

Where Time Series Software implements or otherwise enables forecasting
abilities, it should return one of the following three kinds of
information. These are presented in decreasing order of preference, such
that software should strive to return the first kind of object, failing
that the second, and only the third as a last resort.

-   **TS4.6** *Time Series Software which implements or otherwise
    enables forecasting should return either:*
    -   **TS4.6a** *A distribution object, for example via one of the
        many packages described in the CRAN Task View on [Probability
        Distributions](https://cran.r-project.org/web/views/Distributions.html)
        (or the new [`distributional`
        package](https://pkg.mitchelloharawild.com/distributional/) as
        used in the [`fable` package](https://fable.tidyverts.org) for
        time-series forecasting).*
    -   **TS4.6b** *For each variable to be forecast, predicted values
        equivalent to first- and second-order moments (for example, mean
        and standard error values).*
    -   **TS4.6c** *Some more general indication of error associated
        with forecast estimates.*

Beyond these particular standards for return objects, Time Series
Software which implements or otherwise enables forecasting should:

-   **TS4.7** *Ensure that forecast (modelled) values are clearly
    distinguished from observed (model or input) values, either (in this
    case in no order of preference) by*
    -   **TS4.7a** *Returning forecast values alone*
    -   **TS4.7b** *Returning distinct list items for model and forecast
        values*
    -   **TS4.7c** *Combining model and forecast values into a single
        return object with an appropriate additional column clearly
        distinguishing the two kinds of data.*

### 5 Visualization

Time Series Software should:

-   **TS5.0** *Implement default `plot` methods for any implemented
    class system.*
-   **TS5.1** *When representing results in temporal domain(s), ensure
    that one axis is clearly labelled “time” (or equivalent), with
    continuous units.*
-   **TS5.2** *Default to placing the “time” (or equivalent) variable on
    the horizontal axis.*
-   **TS5.3** *Ensure that units of the time, frequency, or index
    variable are printed by default on the axis.*
-   **TS5.4** *For frequency visualization, abscissa spanning
    \[ − *π*, *π*\] should be avoided in favour of positive units of
    \[0, 2*π*\] or \[0, 0.5\], in all cases with appropriate additional
    explanation of units.*
-   **TS5.5** *Provide options to determine whether plots of data with
    missing values should generate continuous or broken lines.*

For the results of forecast operations, Time Series Software should

-   **TS5.6** *By default indicate distributional limits of forecast on
    plot*
-   **TS5.7** *By default include model (input) values in plot, as well
    as forecast (output) values*
-   **TS5.8** *By default provide clear visual distinction between model
    (input) values and forecast (output) values.*
