File formats
The structure, table, project, workflow, model, curation and report files that GeinQSAR Studio reads and writes, and what each of them keeps.
GeinQSAR Studio reads and writes the common exchange formats of chemistry for structures and tables, and uses a few formats of its own for projects, workflows and models. The program's own formats are either plain JSON, which can be read by any text editor and archived as it is, or a binary container with a checksum for every part, which detects any damage when the file is opened.
Structure and table files
| Format | Extensions | Read | Written | Notes |
|---|---|---|---|---|
| SD file / MOL file (V2000 and V3000) | .sdf, .sd; .mol, .mdl | Yes | Yes | Several molecules per SD file, one per MOL file. Data fields become columns. |
| SMILES list | .smi, .smiles, .ism, .can | Yes | Yes | One SMILES per line, optionally followed by a name. |
| CSV and TSV tables | .csv; .tsv, .tab; .txt | Yes | Yes | A column of SMILES plus any number of value columns. |
| MOL2 | .mol2, .ml2 | Yes | Yes | Atom types and partial charges are kept. |
| PDB | .pdb, .ent | Yes | Yes | Each MODEL is one molecule; bond orders are worked out from the geometry. |
| PDBQT | .pdbqt | Yes | Yes | Partial charges, atom types and the torsion count are kept. |
| XYZ | .xyz | Yes | Yes | Several frames per file; bonds are worked out from the geometry. |
The extension decides the format. A file with an unknown extension, or .txt, is recognised from its first lines (a MOL2 header, a V2000 or V3000 counts line, PDB records, an XYZ atom count, a table header that names a SMILES column, or else a SMILES list). Compressed files are not read; unpack them first.
.sdf, .sd, .mol, .mol2, .pdb, .xyz, .smi, .smiles, .ism, .can, .csv, .tsv and .txt. The other extensions of the table (.pdbqt, .ent, .ml2, .mdl, .tab) are read by the Read molecules node of a workflow and by gqsar-cli; rename such a file to import it into a spreadsheet. Spreadsheet workbooks (.xlsx, .xls, .ods) are not read: save the sheet as CSV.A record that cannot be read never stops the rest of the file. It is reported with its line number, and the reading continues with the next record. In the spreadsheet the problems are written to the Log panel (see Troubleshooting).
SD and MOL files
Both the V2000 and the V3000 form are read. The program keeps the molecule name (first line of the record), formal charges, radicals, isotopes (deuterium and tritium included), the chiral flag, atom parities, wedge and hash bonds, atom maps and every data field (> <name>), which becomes a column. 2D or 3D coordinates are taken as given. Query atoms are read but carry no element; S-group and collection blocks are skipped. A damaged record is reported (for example MOL/SDF: truncated record: counts line declares ... atoms or malformed atom line) and the reader resumes after the next $$$$.
Files are written in V2000 with Kekulé bonds and the data fields of each molecule. The V3000 form is used automatically for a molecule that V2000 cannot hold: more than 999 atoms or bonds, dative or zero-order bonds, charges beyond ±15.
SMILES lists
One SMILES per line, followed by a space or tab and an optional name. Blank lines and lines starting with # are ignored, and a first line that names a SMILES column is treated as a header. Exported SMILES are canonical and include stereochemistry.
CSV and TSV tables
Quoted fields may contain separators and line breaks. When a table is imported into the spreadsheet, the import dialog detects the separator (comma, semicolon, tab or vertical bar), whether the first line holds column names, and which columns hold the structure, the name, the identifier, the activity and the set membership, and lets you correct each guess. A column is taken as the structure column when its header is one of smiles, canonical_smiles, isomeric_smiles, smi, structure or smiles_string, or when at least 60 % of its sampled values look like SMILES. A file without a structure column cannot be imported until one is chosen.
The Read molecules and Read CSV dataset nodes of a workflow use a comma for .csv and a tab for .tsv unless another separator is set, and name the SMILES and name columns in their parameters; with the columns left empty they look for the usual header names.
MOL2, PDB, PDBQT and XYZ
- MOL2 keeps the atom types and partial charges and the molecule name. MOL2 has no field for formal charges, so they are worked out from the valences when the file carries explicit hydrogens. Written files contain explicit hydrogens and the partial charges when there are any.
- PDB reads each MODEL as one molecule, takes the element from columns 77 and 78 (or from the atom name) and keeps only the first alternate location. Bonds come from CONECT records or, without them, from the distances; bond orders and charges are always worked out from the geometry, so check a ligand taken from a crystal structure before modelling it.
- PDBQT additionally keeps the partial charges, the atom types and the torsion count, and writes a torsion tree.
- XYZ reads several frames, takes the comment line as the name and works out bonds from covalent radii.
Exporting a dataset
File > Export (Ctrl+E) opens the export dialog, which writes the active dataset in one of five forms. The dialog chooses the rows (All, Selected or Filtered) and the columns (Visible, All or Chosen).
| Form | What is written | When to use it |
|---|---|---|
| CSV | Comma-separated, Windows line ends, column headers with their units (for example MW (g/mol)). | Exchange with other programs and scripts. |
| CSV for a spreadsheet program | The same, starting with a UTF-8 byte order mark. | Opening in a spreadsheet program, which otherwise garbles accented characters and symbols. |
| Tab-separated text | Tab-separated, one line per row. | Pasting into documents and statistics programs. |
| SD file | One record per row, titled with the name (or the identifier); every chosen column becomes a data field. Missing 2D coordinates are generated when Generate missing 2D coordinates is on. Alignment and preparation records of the 3D-QSAR workflow are always included. | Passing structures with their data to a modelling or docking program. |
| SMILES | Canonical SMILES, a tab, and the name or identifier. | A compact list for a database search or another program. |
2D-QSAR > Export the model matrix opens the same dialog with the identifier, name, set, activity and descriptor columns chosen, which is the table a statistician needs to refit a model.
Files of the program itself
| File | Format | What it holds |
|---|---|---|
Project .gqproj | Binary container, format version 1.0 | The datasets and workflows of a session. Described on Projects and files. |
Workflow .gqflow | JSON ("format": "GeinQSAR.Workflow", version 2) | The nodes with every parameter, their positions and comments, the connections, the canvas groups and notes. |
2D model bundle .json | JSON ("format": "GeinQSAR.TrainedModel") | The fitted model with its descriptor names, the descriptor transformations fitted before training (imputation, outlier limits, scaling), the response name, units and transformation, and the applicability domain. |
3D-QSAR model .gqfm | Binary container, format version 1.2 | The complete 3D-QSAR model, described below. |
Curation provenance .curation.json | JSON ("format": "geinqsar-curation") | Everything needed to rebuild a dataset from its source, described below. |
Raw snapshot .raw.json | JSON ("format": "geinqsar-raw-dataset") | The records as downloaded or read, before any curation step. |
Report .pdf, .docx, .xlsx | PDF 1.7; Office Open XML (ECMA-376) | A model, curation or analysis report, written from one document so that the three forms cannot disagree. |
Figure .png, .svg | Image | A chart or a 3D view exported for publication. |
Workflows
A .gqflow file stores every parameter of every node, including the ones left at their defaults, so that the file means the same thing in a later version whose defaults have changed. Seeds are stored as decimal text. A workflow saved in the earlier format version 1 is converted when it is opened, and a note says so. A workflow written by a newer version of the program is refused with workflow format version N is newer than this build supports (version 2); please update GeinQSAR. Input paths in a workflow that are not absolute are resolved against the folder of the workflow file.
2D model bundles
A model saved by the 2D-QSAR wizard, by the Write model node or by gqsar-cli train is one JSON file. Because the transformations of the descriptors are stored with the model, new compounds are transformed exactly as the training compounds were, and the applicability domain travels with it. A bundle saved by a workflow also records the workflow that produced it. Read it back with Wizards > Predict with a saved model (see Predicting new compounds), the Read model node or gqsar-cli predict.
3D-QSAR models (.gqfm)
A .gqfm file holds everything needed to apply and to inspect a KEFRA or an atom-based model. For an atom-based model: the protocol with its seeds, the lattice, the columns that survived filtering and the block scaling, the PLS state and the full field matrix, the StDev x Coeff map, all statistics (bootstrap, response scrambling, leave-group-out, fitted, cross-validated and test values) and the compound identifiers with their training and test assignment. For a KEFRA model: the whole KEFRA model record with its settings and the choices of its cross-validation. Both hold the aligned molecules with their alignment records and the preparation record of the training compounds. Opening the file with File > Open shows the model in its dashboard.
Format 1.1 added the preparation record and a final checksum over the whole file; format 1.2 added the KEFRA model. Atom-based models in format 1.0 still open, with their preparation shown as not recorded. A file of another major version is refused with a message that names its version, and a model of a kind this version no longer offers is refused as described on The 3D-QSAR wizard.
.gqfm file contains the training structures and their activities. Treat it as being as confidential as the dataset itself.Dataset Builder files
Saving a dataset in the Dataset Builder, or running gqsar-cli fetch or curate with -o name.csv, writes a family of files with the same stem in one folder:
| File | Content | Written |
|---|---|---|
name.csv | The curated table (UTF-8). | Always |
name.curation.json | The provenance: software and version, the source (database, release, query, time of access, every request), the options chosen and the options in effect, the in and out counts and removal reasons of every step, the findings, and the SHA-256 checksums of the table and the structure file. | Always |
name.sdf | The structures with 2D coordinates and the table columns as data fields. It carries no time stamp, so the same curation gives a byte-identical file. | Structures (SD file) |
name.raw.json | The raw records before curation. | Raw snapshot |
name.removed.csv | One line per removed record: record and compound id, step, reason code, reason, detail, type, relation, value, units, assay, document and SMILES. | Removal log |
name.report.txt | The curation report as plain text. | Report (text) |
name.report.pdf | The same report as a paged PDF, with the company logo, the name of the program, the date and time it was written and the report identifier on every page. | Report (PDF) |
name.report.docx | The same report as a Word document, with real headings and tables and a table of contents. | Report (Word) |
name.report.xlsx | Every table of the report on a sheet of its own. | Report (Excel) |
The provenance file is the record to archive with a publication: Data > Replay a provenance file and gqsar-cli curate --replay rebuild the table from it and confirm by checksum that it is identical (see Provenance and replay). Without the raw snapshot or the response cache, a replay has to query the database again.
Reports and figures
A report is written as a PDF (.pdf), a Word document (.docx) and an Excel workbook (.xlsx), in any combination, from one document, so the three cannot disagree. Each is a single file that needs nothing from outside it: charts and structures are drawn as vector graphics inside the file. A report can therefore be sent by e-mail, archived or attached to a submission as it is. Every page carries the company logo, the name of the program, the title, the report identifier and the date and time the report was written. The report dialogs can also write the predictions as CSV or SD file and every table of a dashboard as CSV. See Reports and export.
Charts are exported as SVG or PNG; 3D views as PNG, with the resolution stored in the image so that it is placed at the right size in a document. Sizes, resolutions and the other figure options are described on Publication figures.