[INTRODUCTION]

This is the recommended format for time series data in BioSPICE applications.
The format is a simplified version of the time series format used in JigCell.
Simplifications were made for two reasons:

1) It was considered unlikely that a sufficient userbase would take advantage of
   the more complex features such as inline annotations at this time.
2) To eliminate the use of XML.  The proposed time series format is structured
   text with very little overhead.

Two formats are proposed: a general data format and a specialized format for a
2D time series of real values.  Although the general format isn't particularly
complex, the specialized format is easier to implement and will probably be
sufficient for many current simulation needs.  The specialized format is a
subset of the general data format.  Any conforming parser for the general data
format correctly parses the specialized format.

[VERSION]

This is a draft specification for the second version of the time series format.
It was last updated May 18th, 2004.

[GRAMMAR]

* [0-9] is the character class containing the digits 0 through 9.

* [^"] is the character class containing all characters except for the quotation
  mark.

* [^\"] is the character class containing all characters except for the
  backslash and quotation mark.

* The contents of a pair of single quotes ' ' form a terminal.  The quotes are
  not part of the terminal.

* | represents a choice between multiple options; * represents 0 or more
  instances of an option

[GENERAL DATA FORMAT V1]

The version one general data format is the original time series format used
in BioSPICE.  It is defined by the following grammar:

  element = scalar | list

  scalar = boolean | integer | real | literal | null

  list = '(' elements ')'

  elements = element | element ',' elements

  null = '' | 'No Value'

  boolean = 'true' | 'false'

  integer = digit digits | '-' digit digits

  digit = [0-9]

  digits = digit*

  literal = '"' chars '"'

  char = [^"]

  chars = char*

  real = float | '-' float | specialfloat

  specialfloat = 'NaN' | 'Infinity' | 'Inf' | '-Infinity' | '-Inf'

  float = decimal | scientific

  decimal = digit digits '.' digits

  scientific = decimal 'E' integer

[GENERAL DATA FORMAT V2]

The version two general data format allows for the use of quotes in literals.
It makes the following modifications and additions to the version one general
data format:

  char = [^\"] | '\\' | '\"'

When displaying an escaped literal, applications may present the pair '\\' as a
single backslash and the pair '\"' as a single quotation mark if desired.  Note
that other character pairs starting with '\' are not included in the format.
For compatibility with other progams, such occurences may be handled in an
implementation defined manner.

[SPECIALIZED DATA FORMAT]

The specialized data format may be used with either version of the general data
format.  The specialized format makes the following modifications and additions
to the general data format:

  element = '(' series ')' | null

  series = list | list ',' series

  elements = scalar | scalar ',' elements

  scalar = real | null

In the specialized format, the legal time series directly mimic the structure of
a two dimensional array of doubles.  An example of a legal time series in the
specialized format:

((0.0,0.0,0.0),(0.1,0.2,0.3),(0.2,0.4,0.3))

which could also be depicted as (with example column labels for clarity):

Time   X    MPF
0.0   0.0   0.0
0.1   0.2   0.3
0.2   0.4   0.3

[IMPLEMENTATION NOTES]

* The character set for transfer must be UTF-8.  Implementations may convert the
  data to other character sets for display or their internal representation.

* White space is only significant inside of scalars and terminals.

* Terminals are not case sensitive.

* Implementations may have more restrictive definitions of numerical and literal
  formats depending on the internal representation used.

[CONTACT]

Author: Nicholas Allen (nallen@vt.edu)