GeinQSAR Studio
Home › Designing a library

Designing a library

LIBQORA builds the molecules a scaffold and a set of substituents imply, computes their properties, predicts their activity with your own model, and ranks them.

LIBQORA (LIBrary design by QSAR-Oriented Ranking Analysis) answers the question that follows a finished model: which molecules should be made next. It takes a core with marked attachment points, or a single hit to decorate, joins the substituents you choose, discards the products you do not want, predicts each one with the models you supply, and puts the library in an order you define. Nothing leaves the program but a table, an SD file and a report: the molecules are proposals for synthesis, not results.

Open it with Wizards > LIBQORA library design, or from the card of the same name on the welcome page. The wizard has seven pages: Scaffold, Substituents, Filters, Models, Interval, Ranking and Output. Design on the last page runs it and opens the library dashboard.

Nothing is pre-selected. The scaffold is empty, no substituent class is ticked, every filter is off, no model is chosen and the prediction interval is switched off. A design is the result of choices you can name afterwards, which is what makes it defensible in a report.
A predicted value is not a measured one. Every number this wizard produces is an extrapolation from the compounds the model was fitted on, and the molecules of a designed library are by construction not those compounds. Read the applicability domain and the prediction interval before the ranking, and treat the ranking as an order in which to test, not as an answer.

Scaffold

The Scaffold page with a carbamate core. The line under the field counts the attachment points the scaffold carries and names them, so a mistyped marker is visible before the next page.
The Scaffold page with a carbamate core. The line under the field counts the attachment points the scaffold carries and names them, so a mistyped marker is visible before the next page.

Design from chooses between the two ways of generating molecules.

ChoiceWhat it builds
A scaffoldA core with numbered attachment points, varied at every point at once. The Scaffold field takes SMILES in which each position to vary carries a numbered marker, [*:1], [*:2] and so on; each marker must have exactly one neighbour. The combinatorial product of the substituent lists is enumerated.
Existing moleculesSingle-point substitutions on a hit: every analogue differs in exactly one position. The molecules come from a dataset, and Positions to substitute takes a SMARTS pattern, [cH] by default, which is every aromatic carbon that carries a hydrogen. Only matched atoms that carry a hydrogen are used.
ControlDefaultWhat it does
ScaffoldEmptyThe core, as SMILES with numbered attachment points. The status line reads, for example, 1 attachment point: R1 or 2 attachment points: R1, R2, and turns red with the reason when the SMILES cannot be read.
Positions to substitute[cH]Decorating a hit: the SMARTS pattern that marks the atoms to substitute.
Keep the parent molecule in the libraryOffDecorating a hit: puts the unchanged molecule in the library as well, so the analogues can be compared with it in the same ranking.
Standardize the structures that are readOnDecorating a hit: puts the molecules read from the file through the standardisation of Preparing the data first. Standardization options opens its settings.

Substituents

The Substituents page with three of the 33 classes of the built-in library ticked. Nothing is ticked when the page opens, which means the whole library. Scrolling the page brings the cap, the random sample and the stereochemistry into view, and above them a line that multiplies out the combinations the current choice implies, so a library of the wrong size is caught before it is built.
The Substituents page with three of the 33 classes of the built-in library ticked. Nothing is ticked when the page opens, which means the whole library. Scrolling the page brings the cap, the random sample and the stereochemistry into view, and above them a line that multiplies out the combinations the current choice implies, so a library of the wrong size is caught before it is built.

Substituents from chooses the source.

ChoiceWhat it reads
Built-in libraryThe groups shipped with the program: 319 substituents in 33 classes, every one of which attaches to an aromatic carbon without a valence error, and no two of which are the same group. The Classes boxes restrict it; nothing ticked means the whole library.
FileA .csv or .tsv with a smiles column, or a file with one SMILES per line. Each entry carries exactly one attachment point, [*].
Substituents (a typed list)One per line: a SMILES with exactly one [*], optionally followed by a name. A line R1: or R2: starts the list of one attachment point, so each point can be varied over groups of its own.
ControlDefaultWhat it does and when to change it
Maximum molecules10000A hard cap. The enumeration stops there and says so, rather than filling the memory of the machine. Raise it only when the library is meant to be that large and the ranking will reduce it again.
Random sample0Draws this many combinations at random instead of enumerating every one; 0 enumerates everything. Use it when the product of the lists is far larger than the cap. The sample is reproducible from the seed on the Output page.
Remove duplicate productsOnProducts that are the same molecule by canonical SMILES are kept once. Two different substituent combinations often give one molecule on a symmetric core.
Standardize the productsOffPuts the built molecules through standardisation. Off by default, because a product built from standardised parts normally needs nothing further.
StereochemistryAs suppliedAs supplied keeps the stereochemistry the scaffold and the substituents carry. Remove drops it, which is right when the synthesis will give a racemate.

Products that are not built

A combinatorial enumeration joins whatever two lists put next to each other, and some of those bonds belong to no stable drug-like molecule. LIBQORA judges the bond it has just made, and refuses the product when that bond is one of these:

RefusedWhy
A halogen on nitrogen, oxygen, phosphorus or sulfurAn N-halogen such as an N-F carbamate is an oxidant, not a candidate.
A halogen on a halogenAn interhalogen bond.
A peroxide, O-OHydrolytically and thermally unstable.
A disulfide, S-S, made by the enumerationReduced in a cell.
A sulfenate ester, O-S with divalent sulfurHydrolyses readily.
An acyl-O-S mixed anhydrideAs reactive as a carboxylic anhydride.
A carboxylic anhydride, acyl-O-acylAcylates whatever it meets first.
A sulfenamide, N-S with divalent sulfurCleaved by thiols.
A hydrazine N-N, with neither nitrogen acylated or oxidisedOxidised in air.
An unstabilised N-O, an alkoxyamineWeak bond, and a toxicophore.

The rules refuse only the genuinely unstable cases. Sulfate, sulfonate and sulfamate esters keep joining, because such esters are marketed drugs; so do carbonates, ordinary and acyloxyalkyl esters, sulfonamides, sulfinamides, hydrazides, semicarbazides, hydroxamic acids, oximes, N-oxides and any halogen on carbon. The judgement does not depend on which of the two partners the enumeration brought to the bond.

The rules apply only to bonds the enumeration invents. A motif you drew into the scaffold yourself is left alone and is caught, if you ask for it, by Unwanted groups on the Filters page. On the shipped carbamate example 9 of the 319 built-in groups are refused at the carbamate nitrogen, 4 halogens and 5 groups with divalent sulfur, while all 319 attach to an aromatic carbon. The run reports the count and names every refused combination in its enumeration table.

Filters

The Filters page with filtering switched on and no rule chosen, which is how it opens. Each rule has a box of its own, and the ones that take limits reveal them when they are ticked. The page is a list of decisions, not a preset.
The Filters page with filtering switched on and no rule chosen, which is how it opens. Each rule has a box of its own, and the ones that take limits reveal them when they are ticked. The page is a list of decisions, not a preset.

Filter the library switches the whole page on. Every filter is then still off until you switch it on: nothing is discarded that you did not ask to discard. The verdict of every filter on every molecule is kept and reaches the dashboard and the report, so a molecule that is missing from the library can be traced to the rule that removed it.

FilterDefault when switched onWhat it keeps
Lipinski rule of fiveAt most 1 violationThe rule of five, with the number of violations allowed set by you.
VeberRotatable bonds at most 10 and polar surface area at most 140 Å2.
Lead-likenessThe tighter limits of a lead rather than a drug.
QEDAt least 0.5Molecules above a drug-likeness score.
Molecular weight range, logP range, TPSA range, Rotatable bonds range, Donors range, Acceptors range150 to 500, -1 to 5, 0 to 140, 0 to 10, 0 to 5, 0 to 10Each range has its own box and its own two limits, so one property can be constrained without the others.
PAINSRemoves molecules that match a pan-assay interference pattern. The program carries 52 patterns of its own, which are not the whole published set; measured against an independent implementation of the 480 published filters on 7 160 structures they recover 65 % of what it flags, with 60 % precision and 92 % agreement overall. Use it to thin a library, not as proof that a molecule is clean.
Unwanted groupsRemoves molecules carrying a reactive or otherwise unwanted group, by the structural alerts described under Molecular descriptors.
Synthetic accessibilityAt most 6.0A fragment-frequency score from 1, the easiest, to 10. It was fitted on the structures shipped with the program, so it ranks molecules against those; benzene scores 1.00, aspirin 1.83, caffeine 3.95, morphine 8.62.
Training-set similarity0.3 to 1.0Keeps only molecules close enough to the compounds the model was fitted on for the model to speak about them. It needs those compounds: switch on Training set available below the filters and choose the dataset, or the run refuses with the reason.

Models

The Models page with a model bundle chosen. The line under the field reads the file and reports what it predicts and whether it carries an applicability domain, so a model without one cannot be used unknowingly.
The Models page with a model bundle chosen. The line under the field reads the file and reports what it predicts and whether it carries an applicability domain, so a model without one cannot be used unknowingly.
ControlDefaultWhat it does
Model file, BrowseEmptyA 2D model bundle (.json) or a saved 3D-QSAR model (.gqfm), from the 2D-QSAR wizard, the 3D-QSAR wizard or a model dashboard. A design needs no model: it can be ranked on computed properties alone. A model makes the ranking an activity ranking. The description line names the model, the response it predicts, the column it writes, and states in capitals when the model carries no applicability domain.
More modelsEmptyOne file per line. Each model gets a column of its own, which can be an objective of its own, so a library can be ranked for potency and against an off-target at the same time.

Interval

A prediction without a spread is a number without a scale. This page calibrates a prediction interval, and it is a page of its own because the warning it carries has to be read before the four settings are used.

The Interval page as it opens: the interval is off and the page says what that means, Without a calibration set no interval is shown.
The Interval page as it opens: the interval is off and the page says what that means, Without a calibration set no interval is shown.
The same page with a calibration file of 60 measured compounds. The status line counts the compounds that carry a value in the named property and states that the run removes any of them the model records as part of its own fit.
The same page with a calibration file of 60 measured compounds. The status line counts the compounds that carry a value in the named property and states that the run removes any of them the model records as part of its own fit.

Calibrate a prediction interval is off by default, and switching it off again clears the four settings rather than leaving them to take effect silently.

ControlDefaultWhat it does
Calibration setEmptyA file of measured compounds the model was not fitted on. Without it no interval is reported.
Measured valueEmptyThe property of that file which holds the measured value, for example pIC50.
Alpha0.2The interval is built to cover 1 minus alpha of the compounds: 0.2 gives an 80 % interval, 0.1 a 90 % one. Strictly between 0 and 1.
Interval methodSplit conformalSplit conformal gives one half-width to every compound, from the absolute calibration residuals. Normalised conformal lets the half-width follow the model's own standard error, while the calibration still fixes its size.

Why the model's own standard error is not used: that figure is the error of the model's fit. On the first validation of this module a model bundle quoted 0.607 log units while the real spread of its errors on compounds it had never seen was 0.947, so an interval taken from it would have been about a third too narrow. Split conformal prediction builds the interval instead from residuals the model never saw (Papadopoulos and colleagues, ECML 2002; Norinder and colleagues, J. Chem. Inf. Model. 2014, 54, 1596). On the shipped example the calibrated 80 % interval covered 20 of 25 held-out compounds, that is 80.0 %, where an interval from the model's own standard error covered 15 of 25.

The wizard refusesBecause
A calibration set with fewer than 20 compoundsWith n compounds the finest coverage that can be certified is 1 minus 1/(n + 1), so below 20 no interval is reported rather than an approximate one. The message names the number the file holds.
A coverage finer than the set can certifyThe message says what the file can certify and offers the two ways out: raise alpha, or calibrate on more compounds.
A calibration file with no measured-value property namedThere is nothing to compare with.
Any of the four settings while the interval is offA setting that has no effect is a setting that misleads.
A calibration set without a modelAn interval is calibrated against a model.
Between 20 and 100 compounds the page warns that the validation programme could not certify the coverage, so the interval is to be read as approximate. The reason is in the measurement: pooled over the data sets of the validation the coverage was at its nominal rate, but on an individual data set it missed that rate in 39 % of cases, by up to 11 percentage points either way. Every data set whose interval was certified carried 97 or more calibration compounds.

Ranking

The Ranking page with one objective, the predicted activity, and a diverse subset of 12 switched on. The line under the field lists every column this design will produce, so an objective can only be named on a value that will exist.
The Ranking page with one objective, the predicted activity, and a diverse subset of 12 switched on. The line under the field lists every column this design will produce, so an objective can only be named on a value that will exist.

Objectives is where a library becomes a list. Each objective is written as <column> maximise, minimise or target, with optional weight=, low=, high= and target=; several objectives are separated by semicolons. Without low and high the limits are taken from the library itself. Columns you can rank by names every column that will exist: the predicted value of each model, the computed properties, the scores of the filters and the similarity to the training set.

pIC50 maximise; QED maximise weight=0.5
pIC50 maximise low=5 high=9; MW target target=380; SA minimise
ControlDefaultWhat it does
RankingDesirabilityDesirability maps every objective onto 0 to 1 and combines them with their weights into one number, which gives a single order. Pareto fronts keeps the objectives separate and groups the molecules into fronts, so the trade-offs are visible instead of averaged away.
Mix domains in the rankingOffOff: every molecule the models can vouch for is ranked above every molecule they cannot. Switching it on lets predictions that are extrapolations reach the top of the list.
Drop out-of-domain moleculesOffRemoves them instead of ranking them last. Off by default, because a molecule outside the domain is still information: on the shipped example the 23 flagged molecules of 319 had the higher mean predicted activity, which is what extrapolation looks like.
Select a diverse subsetOffA MaxMin selection on fingerprint distances: a short list that spans the chemistry of the library instead of a block of near-identical analogues.
Compounds to select24How many the selection returns.
Choose from the best0Consider only this many of the best-ranked molecules; 0 uses the whole library. A small number keeps the diverse set potent, a large one makes it diverse.
Start from the best-ranked moleculeOnThe selection begins with the top of the ranking rather than with an arbitrary molecule.

Output

The Output page. Both file paths are shown in full, so it is clear before the run where the library will land. Unless they are changed they are under Documents\GeinQSAR\Output.
The Output page. Both file paths are shown in full, so it is clear before the run where the library will land. Unless they are changed they are under Documents\GeinQSAR\Output.
ControlDefaultWhat it writes
Write the ranked library as CSVOnThe whole ranked table, every column of the run.
Write the structures as an SD fileOffThe structures with their results as data fields, for a program that takes structures.
Random seedThe program's own seedThe same settings and the same seed give the same library, byte for byte. Change it to draw another random sample or another diverse subset.

At least one of the two files must be chosen, or the run leaves nothing behind and the page says so. Design runs the workflow and opens the dashboard; a notification counts the molecules ranked, those selected for diversity, and names the file.

From a workflow and from the command line

The wizard builds an ordinary workflow, so a design can be rerun, edited and put into a longer computation. The template LIBQORA library design in the template gallery (see Workflow templates) fits a model to a measured series and designs around a scaffold of its actives in one run, on the shipped acetylcholinesterase sample of 429 compounds. Five nodes do the work:

NodeWhat it does
Enumerate libraryThe combinatorial product of the scaffold and the substituents.
Decorate a hitSingle-point analogues of the molecules on its input.
Filter libraryThe rules of the Filters page, with the training set on its second input for the similarity filter. Its second output is the verdict of every filter on every molecule.
Score and rank libraryThe models, the computed properties, the prediction interval and the ranking. A model reaches it either as a file parameter or through its Model input, so a model fitted in the same workflow can be used without being saved first.
Select diverse compoundsThe MaxMin selection.

On the command line, gqsar-cli design does the same work. --objectives is required, because a design with no objective has no order.

gqsar-cli design --scaffold "NC(=O)c1ccc([*:1])cc1" --classes alkyl,halogen,heteroaryl ^
    --model ache_model.json --filter lipinski,pains --objectives "pIC50 maximise; QED maximise weight=0.5" ^
    --select 24 -o designed_library.csv --sdf designed_library.sdf

gqsar-cli design --decorate hit.sdf --sites "[cH]" --model ache_model.json ^
    --calibration calibration.csv --activity pIC50 --alpha 0.2 --objectives "pIC50 maximise"

The options follow the pages: --scaffold or --decorate with --sites, --substituents or --classes, --filter with the names of the rules to apply (none is applied unless named), --training, --model once per model, --calibration with --activity, --alpha and --interval, --rank, --select and --from-top, --sample, --max, --seed and --stereo. --alpha, --interval and --activity without --calibration are refused rather than ignored. The full list is in The command line.