wiki:ExportFormat

Version 1 (modified by flip, 10 years ago) (diff)

--

Our export format doesn't have rigorous documentation or an XSD. In lieu of that, you can get a long way by studying the output of an export. It's pretty straightforward. Some of the subtle points are explained below.

The Export Comment

Each export contains a comment. This is informational only; our applications ignore it when importing.

Timestamps

Timestamps are always in combined ISO format, e.g. 2010-04-30T15:14:56. The seconds field is always present, and there's never time zone information.

Timestamps are always in the local time of the machine that wrote them. Using local time isn't ideal for files that are meant to be shared globally, but time zone information in Python isn't easy to deal with and we opted not to.

Missing Fields

In general, our import code doesn't care if optional fields are present and empty or simply not present. If it's not present, our code assigns a default value.

For instance, a blank comment can be represented as <comment /> or simply not present at all.

It's not valid for mandatory fields to be missing; e.g. each metabolite element must contain at least one spin element.

UUIDs

An object's UUID is stored in its id attribute.

It's valid for objects in an export file to lack a UUID. In this case, when they're imported, a new id is assigned. This makes it easier to import objects from 3rd party software into Vespa -- if you can convert the 3rd party format into our format, we'll import it.

Experiments

Experiments export files always include the metabolites and pulse sequence to which the experiment refers. In other words, each experiment contains all the information you need to recreate it.

When metabolites are referred to in simulations, the export file doesn't repeat the entire metabolite definition, only the id. It's guaranteed that the id refers to a metabolite defined in the same experiment element.

Experiments exports don't always include the experiment results. It's up to the user who does the export whether or not the results will be included.

Compression

Export files may be compressed; the compression is compatible with gzip. Our applications examine the file contents (not the file name) to determine whether or not a file is compressed.