GeinQSAR Studio
Home › Reports and export

Reports and export

The report of a dashboard or a workflow as PDF, Word and Excel, the tables behind it, and the files a dataset, a model and a run can be written to.

A report holds the statistics, the figures and the tables of a result, judged against the OECD principles for the validation of QSAR models. It is written in three formats, from one document: a PDF for reading and for attaching to a submission, a Word document for a report that will be edited further, and an Excel workbook for the numbers. Because all three come from the same document they cannot disagree with one another, and because a report never recomputes anything it cannot disagree with the dashboard or with the files the workflow wrote.

The three formats

FormatWhat it is forWhat it holds
PDF (.pdf)Reading, printing, attaching to a submission or to a manuscript as supporting information.The paged report. A cover page with the company logo, the title, the study, the endpoint, the model, the numbers of training and test compounds, the author, the name and version of the program, the local date and time, the same moment again in ISO 8601 with its zone offset, the report identifier, the company, and the standard the report follows. Then a table of contents, a list of figures and a list of tables, the numbered sections, and appendices for the long tables. Charts and structures are drawn as vector graphics, so they stay sharp at any magnification. The logo, the program name and the title run across the head of every page, and the report identifier, Page X of Y and the time stamp across its foot. The PDF carries bookmarks for every section.
Word (.docx)A report that will be edited, commented on or merged into a larger document.The same sections as real Word headings, with a table of contents, a list of figures and a list of tables that fill themselves when the document is opened, and tables that are Word tables rather than pictures of tables. The header and footer carry the same logo, name and stamp.
Excel (.xlsx)The numbers, for a calculation or a plot of your own.A Summary sheet with the cover facts and the statistics, a Predictions sheet, one sheet per table of the report, and a Figures sheet with the figures. Numbers are written as numbers, at the precision they were computed with, not as rounded text.

Paper chooses between A4, the default, and US Letter. It sets the page size and the margins of the PDF and of the Word document; the Excel workbook has no page size. Choose Letter before writing a report for a journal or an agency that asks for it, because the layout is made for the paper rather than scaled to it afterwards.

Every report carries the identifier the program gives it, in the form GQR-YYYYMMDD-HHMMSS-XXXXXXXX, where the last part is computed from the content of the report. Two reports of the same result written at different moments therefore have different identifiers, and a report can be cited by one.

Writing a report from a dashboard

Every dashboard has Export report at the right end of its tab bar. It opens the report dialog; Write report writes the file, and a notification names it.

The Statistics tab of a 3D-QSAR dashboard, with Export report on the tab row and Save model on the row of the model statistics.
The Statistics tab of a 3D-QSAR dashboard, with Export report on the tab row and Save model on the row of the model statistics.
The report dialog of a 3D-QSAR dashboard. The title is taken from the dashboard; Tables as CSV is offered because this dashboard has tables, and is ticked here.
The report dialog of a 3D-QSAR dashboard. The title is taken from the dashboard; Tables as CSV is offered because this dashboard has tables, and is ticked here.
ControlDefaultMeaning, and when to change it
TitleThe name of the dashboardThe heading of the report.
AuthorEmptyShown in the header line of the report.
EndpointEmptyOECD principle 1, a defined endpoint: the assay, the target, the units and how the response was measured. Without it that principle is reported as only partly met.
MechanismEmptyOECD principle 5, the mechanistic interpretation. Left empty, the report states that none was established rather than asserting one.
FiguresOnEmbeds the figures of the dashboard as vector graphics.
Prediction tableOnEmbeds the per-compound predictions.
ProvenanceOnEmbeds the program version, the random seeds and the timings.
Tables as CSVOffShown when the dashboard has tables. Also writes every table of the report as a CSV file next to it, named after the report and the table (<report>_<table>.csv); the tooltip lists the files. For a 3D-QSAR report these are the per-factor statistics, the field contributions, the model statistics, the per-compound predictions, the alignment report and the contour levels; for a 2D model report the cross-validated predictions, the Y-randomization runs and the per-compound applicability domain; for a classifier the cross-validated predictions, the permutation scores and the applicability domain; for a cliff analysis the pair table.
FormatsPDFWhich of the three formats are written. At least one must be chosen, or the dialog refuses. Word and Excel are off by default, so a report is one file unless more are asked for.
PaperA4A4 or US Letter, for the PDF and the Word document.
Report file, BrowseNamed after the dashboardWhere the report is written. The Word and Excel files take the same name with their own extension.

The workflow that produced the result is embedded when it is still open, which completes OECD principle 2 (an unambiguous algorithm). When it was closed the dialog says No workflow attached: keep the workflow open to embed it, and the report documents the model and its parameters but not the pipeline.

An option that cannot be honoured is an error, not a silent omission. If Tables as CSV is ticked and there is no table to write, the dialog says so after writing the report. The PDF is written only after its own layout has been checked for overlapping boxes, text crossing a margin, clipped cells and labels colliding inside a chart; a layout that fails that check is reported as a fault rather than left to be discovered on a printed page. A chart label that cannot be placed clear of its neighbours is left out rather than drawn over them.

Writing a report from a workflow

Workflow > Export report writes the report of the last run of the active workflow, from every result the run produced. Its dialog has the same fields as above (the title defaults to the name of the workflow) and three more: Workflow embeds the whole workflow with every parameter, Predictions as CSV and Predictions as SD file also write the predictions to the files named under each box. The two prediction options need a Predict node in the workflow; without one the report is written and the dialog says why the predictions were not. Before the first run the dialog says Run the workflow first.

Inside a workflow the Report node writes the same report every time the workflow runs, in the formats its own PDF, Word and Excel parameters name, with its own Paper and a Maximum table rows above which a long table is cut in the PDF and the Word file while the Excel workbook keeps every row. gqsar-cli run --report FILE writes it from the command line with the workflow embedded. A workflow saved by version 1.1.0, whose node was called HTML report, still opens: the old node identifier is read as this node.

What a report contains

Each section appears only when the run produced what it describes.

SectionContent
Executive summary, Warnings of the runWhat was modelled, what the model is, and how well it predicts, in the order the figures should be read: the cross-validated and external statistics first, the fit afterwards and labelled as a fit. Then everything the run reported about the data or the model, in one place.
Data setThe source and the curation, and the distribution of the activity. When a series has a narrow activity range or dense activity cliffs, a Series guidance row gives the measured values and what our validation found on such series; it is an observation, not a verdict on the model (see The 2D-QSAR wizard).
MethodsThe descriptors, the data split, the model with every parameter, the validation protocol, the workflow, and the software with its version and its seeds.
ModelThe equation, the latent variables, the descriptor contributions and, for a fingerprint model, the substructures the fingerprint descriptors stand for.
3D-QSAR modelThe field contributions, the statistics of the model, the alignment and the contour maps from several directions with the value of each lobe.
ValidationThe goodness of fit, internal and external validation, observed against predicted, the residual analysis with the bias, the spread, the two trend tests and the compounds beyond 2.5 standard deviations, the Y-randomisation runs, the applicability domain, and the acceptance criteria: every metric with its literature criterion, its verdict and its reference, per set.
PredictionsThe test set, and the predictions of the compounds given to the model.
Designed libraryFor a library design: the ranked library, the verdict of every filter, the charts, and the designed compounds in a structure grid with their predictions, their intervals and their domain status.
Structure-activity landscapeFor a cliff analysis: the counts, SARI with the note on its normalisation, the chirality-cliff counts, Pfeiffer's rule or the statement that it is not testable, and the curation warnings.
Pharmacophore hypothesesThe ranked hypotheses with their scores.
Figures of the validation, further figuresThe charts of the run as vector graphics, each with a caption that says what to look at. Each chart appears once, and when the run holds several models, the title of every figure names the model it belongs to.
Tables of the runEvery table the run delivered (pair tables, fit tables, domain tables), rounded for display with a note that the files hold full precision, truncated at the row limit with a note saying so.
OECD principles checklistA verdict and its evidence for each of the five principles, derived from what the run produced, never asserted.
QMRF summaryThe fields of the QSAR Model Reporting Format, with the fields the run does not determine left blank rather than guessed.
AppendicesThe long tables, each in an appendix of its own: the per-compound predictions (identifier, observed, predicted, residual, standard error and domain verdict with its reasons; for a classifier the classes, the class the statistics describe and one probability per class), the complete metric table, the model coefficients, the tables of the run, and the workflow parameters node by node with every parameter that differs from its default.
Mechanistic interpretationThe text you gave, or the statement that none was established.
The report leads with the cross-validated and external figures and labels the training figures as a fit rather than a measure of prediction. That is not modesty: on our own validation the training R2 of the default recipe had a median of 0.85 while the cross-validated estimate tracked the external error to a ratio of 0.97. A reader who is shown the fit first is shown the least informative number first.

A run that has a text output, such as the summary of a chirality-cliff analysis with its warnings and the Pfeiffer regression, can write it as plain text with a Write text node.

Tables as CSV

Besides Tables as CSV in the report dialog, tables reach a file in three ways:

Prediction tables are written at round-trip precision: every number reads back as the same number. Displays and the report round for themselves.

Exporting datasets

File > Export (Ctrl+E) opens the Export dataset dialog for the active dataset; File > Export as SD file and File > Export as SMILES open it on those formats, and the File menu has one more entry for a CSV prepared for spreadsheet programs.

ControlChoices
FormatCSV; CSV with a UTF-8 byte-order mark, which spreadsheet programs need to read accented and Greek characters correctly; Tab-separated text; SD file; SMILES.
RowsAll rows, Selected rows, or Filtered rows, each with its count.
ColumnsVisible columns, All columns, or Chosen columns ticked one by one.
Generate missing 2D coordinatesSD file: lays out structures that have no coordinates, so the file can be depicted.
Canonical SMILESSMILES: writes the canonical form.

The file formats are described in File formats.

Saving models

ModelHow to save itWhat the file holds
2D model bundle (.json)Save the model bundle on the last page of the 2D-QSAR wizard, a Write model node, or gqsar-cli train.The fitted model, the names of the descriptors it expects, its response transform, the preprocessing fitted with it (imputation, outlier limits, descriptor filter, scaling) and its applicability domain. Descriptors are matched by name when it predicts.
3D-QSAR model (.gqfm)Save model on the Statistics tab of the 3D-QSAR dashboard, Save the model in the 3D-QSAR wizard, or a Write 3D-QSAR model node.See below.

Both kinds are applied to new compounds with Wizards > Predict with a saved model (see Predicting new compounds).

The 3D-QSAR model file

A 3D-QSAR model can predict a new compound only if that compound goes through exactly the arithmetic the training set went through and is placed in the frame the training set was aligned in. The .gqfm file therefore holds much more than the coefficients. The file of an atom-based cube model has these parts:

PartContentsNeeded for
ProtocolThe model type and its settings, lattice, column filter, block scaling, PLS and validation settings, seeds.Evaluating the fields of a new compound the same way.
LatticeThe lattice used, the columns that survived the filter, the block scale factors of the training set.Reading exactly the model's columns from a new compound.
PLS stateWeights, loadings, scores, scalers and the number of components chosen.The prediction and its standard error.
Field matrixEvery row in double precision.Column means for missing values, the applicability domain, contribution maps. It is stored, not recomputed, so the model comes back bit for bit.
StatisticsThe per-factor table, field contributions, bootstrap, Y-randomization, repeated leave-group-out, and every compound's fitted, cross-validated and test value.Showing the model as it was reported when it was built.
Preparation recordHow the training compounds were prepared: 3D generation, conformer search, partial charges.Preparing the compounds to be predicted the same way.
Aligned moleculesEvery training compound as aligned, with coordinates, charges and the record of the alignment on the reference molecule.Placing a later compound in the model's frame, and drawing the maps.

A KEFRA file holds, in place of the protocol, the lattice, the PLS state and the field matrix, the whole KEFRA model record: its settings, the field weights, widths and regularisation its cross-validation chose, and what it needs to compare a new compound with the training compounds. The preparation record and the aligned molecules are the same.

The file is a binary container in which every part carries its own version and a checksum, and an end mark shows that it was written completely. File > Open on a .gqfm file shows the model's dashboard again without the workflow that built it.

Projects (.gqproj), which keep the datasets and workflows of a session together, are described with Projects and files.