Changes between Version 2 and Version 3 of ExportFormat


Ignore:
Timestamp:
May 2, 2011, 1:38:54 PM (9 years ago)
Author:
flip
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ExportFormat

    v2 v3  
    1 These are some jumbled thoughts and comments on Simulation export and import.
    2 Much of it will hopefully be true of Analysis and RFPulse, too, once those
    3 apps have export and import.
    4 
    51= Export and Import Technical Notes =
    62
    7 Export and import allow users
    8 to exchange '''experiments''', '''metabolites''' and '''pulse sequences'''
    9 via email or any
    10 other file exchange medium. Thoughtful users could also use export/import
    11 to perform backups, although this is more of a accidental feature than
    12 an intentional one.
    13 
    14 At present, there's no schema describing the XML file format. In lieu of that,
    15 you can get a long way by studying the output of an export. It's pretty
    16 straightforward. Some of the subtle points are explained below.
    17 
    18 == The Export Comment ==
    19 
    20 Each export contains a comment. This is informational only; our applications
    21 ignore it when importing. At the moment, there's no way for users to see the
    22 export comment other than looking directly at the XML.
    23 
    24 == Timestamps ==
    25 
    26 Each file contains a timestamp at the top that marks when the file was
    27 created.
    28 
    29 Some objects contain timestamps, too. Timestamps in our import/export files
    30 are always in
    31 [http://en.wikipedia.org/wiki/ISO_8601 combined ISO format],
    32 e.g. `2010-04-30T15:14:56`. The seconds field is always present, and there's
    33 never time zone information.
    34 
    35 Timestamps are always in the local time of the machine that wrote them.
    36 Using local time isn't ideal for files that are meant to be shared globally,
    37 but time zone information in Python isn't easy to deal
    38 with and we opted not to.
    39 
    40 == Missing Fields ==
    41 
    42 In general, our import code doesn't care if optional fields are present
    43 and empty or simply not present. If it's not present, our code assigns
    44 a default value.
    45 
    46 For instance, a blank comment can be represented as `<comment />` or
    47 simply not present at all.
    48 
    49 It's not valid for mandatory fields to be missing; e.g. each metabolite
    50 element must contain at least one spin element.
    51 
    52 == UUIDs ==
    53 
    54 An object's UUID is stored in its id attribute.
    55 
    56 It's valid for objects in an export file to lack a UUID. In this case, when
    57 they're imported, a new id is assigned. This makes it easier to import objects
    58 from 3rd party software into Vespa -- if you can convert the 3rd party format
    59 into our format, we'll import it.
    60 
    61 == Metabolites and Pulse Sequences ==
    62 
    63 The export of an metabolite or pulse sequence is straightforward. The
    64 object's attributes are expressed in XML.
    65 
    66 == Experiments ==
    67 
    68 An experiment is more complicated
    69 because it references a pulse sequence and one or more metabs. The pulse
    70 sequence isn't difficult to deal with because there's at most one so its
    71 XML nodes are simply included as a subtree of the experiment.
    72 
    73 The metabolite definitions are children of the experiment, just as the pulse
    74 sequence is. However, each metabolite is also referenced from one or more
    75 (probably many more) simulations that are also part of the experiment.
    76 Repeating the metabolite definitions inside the simulations would be
    77 (a) an inefficient use of space and (b) redundant. Instead, simulations
    78 contain only references (by UUID) to the metabolites. It is guaranteed that
    79 any metabolite which is referred to by a simulation has its full definition
    80 in the experiment.
     3This is a brief review of some ideas related to import and export. For
     4detailed documentation on the content of a Vespa import/export file, see
     5[wiki:VIFF the documentation for VIFF (Vespa Interchange File Format)].
    816
    827
    83 == Compression ==
    84 
    85 Simulation gives the option of compressing the export files it creates.
    86 Compression is done with the
    87 [http://docs.python.org/release/2.5/lib/module-gzip.html gzip module in Python's standard library]
    88 and is compatible with the free gzip utility. Simulation encourages the user
    89 to name compressed files with an extension of ".xml.gz" but that's not
    90 strictly necessary.
    91 
    92 When importing a file, Simulation automatically detects whether or not the
    93 file is compressed. Simulation examines the file contents; the filename makes
    94 no difference.
    95 
    96 In short, compression is transparent to the user and nearly transparent to the app.
    97 
    98 == Integrity ==
    99 
    100 Assigning UUIDs to objects is meant to guarantee that e.g. metabolite
    101 `a1b9f07b-3665-4ce8-ba4a-5f454baf9681` will always be a specfic definition
    102 of aspartate. However, nothing prevents a user from exporting that
    103 aspartate and hand-editing the XML to change aspartate's definition.
    104 Guarding against this sort of tampering is simply out of the scope of this
    105 application.
    106 
    107 
    108 == Concepts ==
     8== Export and Import Concepts ==
    1099
    11010 * Import is never destructive. It never overwrites anything in your existing
     
    15353 There's no strong reason for this limitation, I just never wrote the code
    15454 or designed the GUI to support combining export files.
    155 
    156  * '''Import as a menu item.''' Import is implemented as a button on each
    157  of the management dialogs. It could be a main menu item (simply "Import...")
    158  instead of "Import Metabolites...") . In fact this would probably be
    159  necessary if selective imports are implemented.
    160 
    161  Another advantage of moving import to the main menu is that it would resolve
    162  a pet peeve of mine. Each management dialog has a column of buttons to the
    163  left of the list as well as Import & Export below the list, and Close off
    164  on it's own in the lower right. The buttons in the column all act on items
    165  selected in the list, as does Export. From that point of view, Export belongs
    166  in the column. However, it looks strange (IMHO) to separate it from Import,
    167  hence the conundrum.
    168 
    169  If Import were moved to the main menu, the Import button would go away and
    170  Export could move into the column of buttons with its friends.
    171 
    172 
    173 
    174 
    175