Geinium
Home › Exporting results

Exporting results

The results package: the PDF report, every figure as an image file, the numbers behind every figure, and the scientific checks that run first.

An export turns a finished job, or several, into a results package: a folder with a PDF report, every figure as an image file at print resolution, every number behind every figure as a CSV table, and a manifest that lists every file with its checksum. The report, the images and the Results page are three uses of the same figures and tables, so they cannot disagree. Before anything is written, a set of scientific checks runs over the job; their findings go to the export log.

Export results is on the Results page, the Batch page, the File menu and the tool bar (Ctrl+E). The last stage of every pipeline run exports the job automatically into 09_results\<name>_results with the log in 09_results\export.log.

The results package

<name>_results\
  report.pdf                    the PDF report
  manifest.json                 every file with its size and SHA-256, units, settings, checks
  images\
    rmsd.png  rmsd.svg  rmsd.pdf            one set per figure (300 dpi PNG, vector SVG and PDF)
    ligand_torsions_p1.png ...              figures with parts: _p1, _p2
    600dpi\rmsd.png ...                     only when 600 dpi copies are requested
  raw-data\
    mmgbsa_frames.csv  pca_projection.csv  fel.csv  contacts_interactions.csv ...   job tables
    rep1\protein_rmsd.csv  ligand_properties.csv  sse.dat ...                         per replica
    system.json  protein.json  ligand.json  analysis_settings.json  interactions.json

One example export of a 100 ns job has 27 figures (29 image parts with the two parts of the torsion profile), 26 tables and a report of 18 pages. Replica tables are always in a rep<i> folder, also when there is only one replica. A package is first written as <name>_results.partial and renamed when it is complete, so a cancelled or failed export leaves nothing behind and keeps a package that was there before; a new export of the same name replaces the package as a whole.

For several jobs the top level holds the comparison figures and raw-data\comparison.csv, and every compound has its own folder with images, raw data and manifest; there is one combined report. See Comparing compounds.

The Export results dialog

The Export results dialog for one job, with its defaults: all three kinds of content, the company logo, PNG, SVG and PDF at 300 dpi and natural width, nm and kcal/mol, and all 27 figures.
The Export results dialog for one job, with its defaults: all three kinds of content, the company logo, PNG, SVG and PDF at 300 dpi and natural width, nm and kcal/mol, and all 27 figures.
The same dialog with the figure tree open. Figures are grouped by report section; untick a section or a single figure to leave it out of the images and the report.
The same dialog with the figure tree open. Figures are grouped by report section; untick a section or a single figure to leave it out of the images and the report.
ControlChoicesWhen to change it
Jobs, One combined reportShown when several jobs are open; all checked, combined report on.Untick jobs to leave them out. Turn the combined report off only if each job should be exported as a separate package.
DestinationThe folder in which the package folder is created.Choose a folder outside the job folder for packages you will send.
NameThe package folder is <name>_results; default: the job name, or "comparison" for several jobs.Give each export a distinct name if you want to keep versions side by side.
ContentsPDF report, Images, Raw data.Leave all on for a complete record; images only for a quick set of figures.
LogoCompany logo, Image file (PNG, JPG or SVG), None.Use your own logo for reports that leave your organisation; none for a neutral report.
ImagesPNG, SVG, PDF or PNG; 300 dpi or 600 dpi; Natural width, 85 mm, 114 mm, 174 mm.600 dpi or vector files for print; a fixed width when a journal asks for single (85 mm), 1.5 (114 mm) or double (174 mm) columns.
Unitsnm or Å; kcal/mol or kJ/mol.Follow the convention of the journal or the colleagues who will read the numbers.
FiguresAll (n), or "k of n" when some are unticked.Leave out figures that do not apply to your question.
Export, CloseExport starts; while it runs the button reads Exporting and Close becomes Cancel.
Open folder, Open reportEnabled after a successful export.
AcknowledgeAppears only when the report was blocked because a membrane protein was simulated in water.See Scientific checks below.

The dialog remembers its settings between exports. A figure has a layout for each width it supports and is laid out for the width you choose, never scaled, so the type stays at its printed size. A figure without a layout for a width keeps its natural width; with 85 mm this applies to 12 of the 27 figures of a single job, and the command line lists them.

The dialog for two jobs: the job list with One combined report checked, the default name 'comparison', and 45 figures (27 per compound plus 18 comparison figures).
The dialog for two jobs: the job list with One combined report checked, the default name "comparison", and 45 figures (27 per compound plus 18 comparison figures).
The dialog after an export: the status line gives the number of figures and tables and the package folder, and Open folder and Open report are enabled. When the report was blocked, the status line begins with 'Report not written (see the log).'
The dialog after an export: the status line gives the number of figures and tables and the package folder, and Open folder and Open report are enabled. When the report was blocked, the status line begins with "Report not written (see the log)."

If the analyses of a job were made by an older version, the dialog asks "The analyses of <job> were made by an older version. Recompute them now? The simulations are not repeated." Answering no leaves the job unexported.

Units

One export has one length unit and one energy unit, chosen in the dialog or with -units nm|angstrom and -energy kcal/mol|kJ/mol, and recorded in the manifest. Every figure axis, every report table and every CSV follows them: 1 nm = 10 Å, 1 kcal = 4.184 kJ. Time is always in ns. Degrees, K, bar, kg/m³, %, e, u, mM and kT keep their units; free energies of the landscape are given in kT and in the energy unit. The information files (system, protein, ligand and analysis settings) are converted too, with their keys renamed like the columns; interactions.json keeps its nm keys, because the program reads that file back. The files inside the job folder are never converted.

Images

Every figure is written as PNG (300 or 600 dpi, white background, the resolution stored in the file), SVG and PDF. The style is the same everywhere: an open frame with left and bottom axes, no title inside the image, Arial at 7 to 9 pt at printed size, colours chosen to stay distinct for the common forms of colour-vision deficiency. Every curve is the plain line through its per-frame values. Equal input gives byte-identical PNG and SVG files. How figures are made is described on the page How figures are made.

The PDF report

Page 3 of the report of the example: section 2, Protein-ligand RMSD, with its one-line description, the figure with its caption, and the statistics table with the window in its note. The running head carries the report title and the job; the footer the program version, the package name and the page number.
Page 3 of the report of the example: section 2, Protein-ligand RMSD, with its one-line description, the figure with its caption, and the statistics table with the window in its note. The running head carries the report title and the job; the footer the program version, the package name and the page number.

The report is A4 with 18 mm margins, so a 174 mm figure appears at its printed size. Figures are vector graphics, fonts are embedded, and the document has bookmarks for every section and figure. The title is "Molecular dynamics results"; the line under it gives the creation date, the units and the folders of the package. The sections follow a fixed order:

  1. Simulation details (with the protein, ligand and ions tables and the sequence and ligand figures)
  2. Protein-ligand RMSD
  3. Protein RMSF
  4. Protein secondary structure
  5. Ligand RMSF
  6. Protein-ligand contacts
  7. Ligand torsion profile
  8. Ligand properties
  9. Protein compactness and surface
  10. Binding free energy (MM-GBSA)
  11. Principal component analysis
  12. Free-energy landscape
  13. Run quality
  14. Analysis settings (every criterion, fit group, window, bin and model setting)

A section whose figures could not be made is left out and listed under "Not included" with the reason. The wording is neutral: what is shown and how it is defined, without interpretation and without words such as "stable" or "favourable"; drawing conclusions is left to the reader. The findings of the scientific checks are never in the report.

The logo. Company logo uses the logo built into the program; it is placed at the right of the title block on the first page and as a small mark at the left of the running head on every later page. Image file uses your own PNG, JPG or SVG in the same places, drawn at its native resolution with its transparency; None leaves both places empty. On the command line: -logo <file> or -nologo; in a project: export.logo.

Raw data

Every table is a CSV file in UTF-8 with a block of header lines that start with # and hold key: value pairs: the definition of the table, the atom groups with their atom counts, the number of frames, the window, the source files and the criteria. The unit of a column is the suffix of its name (_nm, _A, _kcal_mol, _kJ_mol, _ns, _deg and so on); a column without suffix is dimensionless. An empty cell means "undefined", for example the free energy of an unvisited bin. Tables carry the precision of the analysis and no more. No absolute path of your PC appears anywhere in a package.

manifest.json (schema geinium-export/1) records the program and version, the creation time, the units, the figure style and resolution, the report pages and bookmarks, for every job its figures, tables and statistics with the source of every printed number, the counts of the checks, the analysis settings, and every file of the package with its size and SHA-256 checksum.

Scientific checks and the export log

Before the package is written the job is checked: the simulation details against the production run input and log, the system against what was declared, the statistics against the raw data. Each finding has a severity:

SeverityEffect
BLOCKStops report.pdf until it is resolved or acknowledged with a written justification. Images and raw data are still written.
WARNINGWritten to the log; the report is written.
INFOA note for the record, for example which ligand parameters and protonation were used.

The findings go to the export log only: the Log panel of the application, the console of mdsim export, 09_results\export.log of a pipeline run, or a file given with -log. These lines are from the log of a real export of the dicyclomine complex (four of its seven findings):

Scientific checks of the results export

m3_dicyclomine
  0 blocking, 0 acknowledged, 4 warnings, 3 notes
[WARNING] replicas.min3 @m3_dicyclomine: 1 replica(s): at least 3 independent replicas (different velocity seeds) are needed to report mean ± SD across replicas; the standard deviations of this export are over the frames of one trajectory
[WARNING] convergence.drift @m3_dicyclomine: replica rep1: rmsd drifts by +0.1155 nm between the halves of the analysis window (> 2 x the block-averaged SE 0.0291 nm)
[INFO] ligand.parameters @m3_dicyclomine: ligand parameters: GAFF2 with AM1-BCC charges (net charge +1 at pH 7.4, input +0)
[INFO] ligand.protonation @m3_dicyclomine: Ligand protonation at pH 7.4: input net charge 0, simulated +1: N1 (aliphatic amine) protonated.

Numbers of the statistics tables compared with their declared source in the raw-data tables of the export: 229 of 229 equal
RuleSeverityWhat it checks
details.settingsBLOCKEngine, version, precision, time step, mass repartitioning, ensemble, temperature, pressure and cut-offs of the report against the production run input and log.
membrane.missingBLOCKA membrane protein simulated without a membrane and without a stated reason.
membrane.flag_conflictWARNINGDeclared soluble, but hydrophobic transmembrane-like segments were found.
replicas.min3WARNINGFewer than three independent replicas.
convergence.driftWARNINGThe RMSD differs between the halves of the window by more than twice its block-averaged standard error.
fit.moleculesWARNINGThe fit group spans several molecules.
ligand.parameters, ligand.protonationINFO (BLOCK if the parameters are not stated)How the ligand was parameterised and protonated.
interactions.hbond_tableINFOThe hydrogen bonds of the interaction analysis against the hydrogen-bond occupancy table.
numbers.raw_dataBLOCK on a mismatchEvery number of every statistics table recomputed from the raw-data file it names; comparison.csv against the comparison table.

Acknowledging a blocking finding

The usual blocking finding of a real job is membrane.missing: a membrane protein was simulated in water and no reason was given when the job was set up. The dialog then shows "Report not written: membrane protein simulated in water." and the Acknowledge button.

The Membrane protein dialog opened by Acknowledge. Choose Simulate without a membrane and type the reason in the required field; the export then runs again and the report states the reason in the Membrane row of the simulation details.
The Membrane protein dialog opened by Acknowledge. Choose Simulate without a membrane and type the reason in the required field; the export then runs again and the report states the reason in the Membrane row of the simulation details.

The dialog offers Use a membrane (POPC:CHOL 7:3) and Simulate without a membrane. The first cannot be applied to a finished run; the status line says "A membrane needs a new simulation: Run MD with the membrane option". The second needs a Reason (required), for example the study of a soluble domain, and is recorded as an acknowledgement. On the command line the same is -ack "rule=justification" (repeatable); in a project, export.acknowledged. Changing an acknowledgement repeats only the export stage of the pipeline, never the simulation or the analyses.

An acknowledgement does not make the science right; it makes the decision visible. The 4DAJ examples of this manual are a membrane receptor simulated in water on purpose, and every report of them says so. For conclusions about such a receptor, simulate it in a membrane.

From the command line

mdsim export -job P:\Geinium\Jobs\Tricin-7-O-glucoside_4daj -o P:\Geinium\Export
mdsim export -job P:\Geinium\Jobs\Dicyclomine_4daj P:\Geinium\Jobs\Tricin-7-O-glucoside_4daj -o P:\Geinium\Export -name comparison
mdsim export -job P:\Geinium\Jobs\Tricin-7-O-glucoside_4daj -o out -units angstrom -energy kJ/mol -dpi 600 -width single
mdsim export -job P:\Geinium\Jobs\Tricin-7-O-glucoside_4daj -list
mdsim export -job P:\Geinium\Jobs\Tricin-7-O-glucoside_4daj -o out -ack "membrane.missing=study of the soluble domain"
OptionMeaning
-jobA job folder, its work folder, or a folder of jobs; several give one combined package.
-o, -name, -titleDestination folder, package name, report title.
-units, -energynm or angstrom; kcal/mol or kJ/mol.
-dpi 300|600, -png600, -[no]vectorPNG resolution, additional 600 dpi copies, SVG and PDF files.
-width natural|single|onehalf|doubleAlso 85, 114 or 174 (mm).
-figuresFigure ids separated by blanks or commas; an unknown id is an error and nothing is written.
-[no]report, -[no]images, -[no]rawThe three kinds of content.
-[no]compute, -recomputeCompute missing analyses (default) or redo old ones.
-thresholdOccupancy threshold of the interaction diagram.
-listLists the figure catalogue with the state of every figure for the job; writes nothing.
-checksPrints the findings of the scientific checks; writes nothing.
-ack, -log, -checks-fileAcknowledgement, log file, findings file in the package.
-logo, -nologoAnother logo, or none.
-compound-reportsA report in each compound folder of a combined package.
-timestampA fixed time stamp: two exports of the same input are then byte-identical, file for file.

Exit codes: 0 done, 1 input error, 3 report blocked or an analysis part failed. All other commands are on the page The command line.