2 | | Our export format doesn't have rigorous documentation or an XSD. |
3 | | In lieu of that, you can get a long way by |
4 | | studying the output of an export. It's pretty straightforward. Some of |
5 | | the subtle points are explained below. |
| 5 | = Export and Import Technical Notes = |
| 6 | |
| 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. |
51 | | When metabolites are referred to in simulations, the export file doesn't |
52 | | repeat the entire metabolite definition, only the id. It's guaranteed that |
53 | | the id refers to a metabolite defined in the same experiment element. |
| 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. |
61 | | Export files may be compressed; the compression is compatible |
62 | | with [http://www.gzip.org/ gzip]. Our applications examine the file |
63 | | contents (not the file name) to determine whether or not a file is |
64 | | compressed. |
| 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. |
| 108 | == Concepts == |
| 109 | |
| 110 | * Import is never destructive. It never overwrites anything in your existing |
| 111 | database. If it changes your database at all, it does so by adding to |
| 112 | what's already there. |
| 113 | |
| 114 | * Conflicts can arise between the names of existing objects and imported |
| 115 | objects. When a conflict arises, import creates a unique name for the |
| 116 | imported object. The current algorithm adds a timestamp to the name, and |
| 117 | if that's still not unique it adds digits until a unique name is found. |
| 118 | |
| 119 | * You can import individual metabolites and pulse sequences from an |
| 120 | experiment export file. |
| 121 | |
| 122 | |
| 123 | == Paths Not Taken == |
| 124 | |
| 125 | * '''Selective imports.''' When the import code reads a file, it assumes |
| 126 | that every object it finds in the XML file that's not already in the |
| 127 | database should be added. The logic is simple. |
| 128 | |
| 129 | It might be nicer for the user if the import code examined the import |
| 130 | file and showed the user a list of importable objects (along with, perhaps, |
| 131 | a list of objects in the import file that already exist in the database). |
| 132 | Naturally, the import dialog would give the user the opportunity to |
| 133 | select which items he wants to import. |
| 134 | |
| 135 | There's nothing wrong or even complicated about this approach, it's just |
| 136 | another dialog and more to design, write, debug, document and maintain. |
| 137 | |
| 138 | * '''Cancelling imports.''' Another thing that a more sophisticated import |
| 139 | GUI could do is offer the opportunity to cancel an in-progress import. |
| 140 | |
| 141 | * '''Combining exports.''' At present, export creates new or overwrites its |
| 142 | target file. It doesn't offer the option to append to an existing file. |
| 143 | Furhtermore, export only exports one kind of object at a time (ignoring |
| 144 | for the moment the fact that exporting experiments implies an export of |
| 145 | metabs and pulse sequences too). |
| 146 | |
| 147 | There's no way, for instance, to export |
| 148 | metabs and pulse sequences to the same file. Nor is there a way to |
| 149 | export one's entire database to a single file (unless one would be |
| 150 | satisified with only exporting in-use metabs and pulse sequences in which |
| 151 | case exporting all experiments would be sufficient). |
| 152 | |
| 153 | There's no strong reason for this limitation, I just never wrote the code |
| 154 | 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 | |