GeinDock Suite
Home › Working with the Co-Scientist

Working with the Co-Scientist

Asking a question, watching the work it leads to, approving long or destructive operations, and the full range of what the assistant can set up, analyse, look up and write.

Working with the Co-Scientist is a conversation in which one side can also operate the software. You say what you want, it decides which operations that takes, carries them out where you can watch, and tells you what it found. This chapter covers what you will see while that happens, the points at which it stops to ask you, and the full range of what it can do.

Asking

Type a request in the message box and press Enter. There is no command syntax to learn. A request can be a question, such as what a residue does, or an instruction, such as preparing a structure, or a whole study described in one sentence. The assistant replies in the language you write in.

Every message you send is accompanied by a short description of the session as it stands: the receptor, the ligands, the binding site, the settings, the results, any running job and what the viewer is showing. That is why you can say the receptor or the best pose without explaining which, and why you can do part of the work by hand between messages: the assistant sees the session as it is now, not as it remembers it.

A question, the operations it led to, and the answer
One exchange. Your message is at the top, the card beneath it records the operations the assistant carried out, and its answer follows, summarising what was done.

Reading an answer

Answers are written as short paragraphs, lists and, where several structures, ligands or poses are being compared, tables. Three things in an answer are live.

In the answer What it does
A residue or a selection written as a linkSelects those atoms in the 3D viewer and centres the view on them. Use it to see at once which residue the text is talking about.
A structure identifier written as a linkDownloads that structure and shows it in the viewer.
A citation or database linkOpens the paper or the database record in your web browser, so the source of a stated fact is one click away.

While the assistant is composing a reply the message shows Thinking, which becomes Thought for and a duration once the reply begins. Click it to read the reasoning behind the answer. The Copy answer button at the end of a finished answer copies its text to the clipboard.

How it works on your session

When a request needs something done, the assistant does it with the application's own operations, one after another, and each one is recorded in an activity card in the conversation. At the same time you see the effect where you would expect it: the structure appears in the viewer, the Docking Panel chips turn green, the Job Queue fills.

An activity card recording a docking run and what followed it
An activity card under the approval that started it. Each row is one operation with a tick and the time it took: the docking run at three minutes, the best pose shown with its score, and a captured view with its Open image link. The Reasoned for rows sit between them.
One row of an activity card expanded
A row opened with a click. Input is the request exactly as it was made, Progress is the commentary while it ran, and Result is what came back.
Part of the card What it tells you
The headingWhile work is in progress, what is happening now, with a spinner. Afterwards, a count such as Ran 4 operations, with the number that failed if any did. Click the heading to fold the card away or open it again.
A rowOne operation, described in plain words, for example the structure being downloaded or the ligands being added. A tick means it succeeded and a cross means it failed. The line beneath gives a one line summary of the result, or the error.
An expanded rowClick a row to open it. Input is exactly what the assistant asked for, Progress is the commentary while it ran, and Result or Error is what came back. This is the place to look when you want to know precisely which chains, which padding or which settings were used.
Reasoned for rowsThe assistant's reasoning on the way to an operation. Click to read it.
Pictures and filesA screenshot it took is shown under its row with Open image. A file it wrote, such as a report, is listed with Open and Show in folder.
A failed operation is reported, not hidden. When an operation fails, the assistant reads the error, corrects the request and tries once more. If it fails again it says so plainly and suggests what you can do. A cross in an activity card followed by a tick is that correction happening.

Operations that open a window, such as a validation, close it again when they finish, so a request carried out by the assistant does not leave the screen cluttered.

The whole window after the Co-Scientist has acted
The window after a request to show the receptor as a surface and zoom in on the docked ligand. The card in the conversation lists the four operations that did it, and the viewer, the Docking Panel and the Interactions panel show the outcome exactly as they would had you taken the same steps by hand.

Approvals

Most of what the assistant does is quick and easily undone, and it simply does it. Two kinds of operation are different, and for those it stops and shows an Approval needed card before anything happens.

Label on the card Operations Why you are asked
Long-runningRunning a docking job, and running a re-docking validation.These take minutes per ligand and occupy your processor. You should decide when that starts.
Replaces current workStarting a new, empty project, and opening a saved project.Both discard the session you have open. Unsaved work would be lost.
An approval card with its three buttons
An approval card waiting for an answer. The sentence says what will run, the Long-running label says why you are being asked, and the plan above shows where the task has got to. Nothing starts until you choose.
Button What happens When to use it
RunThe operation goes ahead, this once.The description is what you intended.
Always allowThe operation goes ahead, and later requests for the same kind of operation in this conversation run without asking.You are working through a series of runs and do not want to confirm each one.
Don't runThe operation is not carried out. The assistant is told you declined and asks what you would like instead, or continues without it.Something in the description is not what you wanted.

The sentence on the card is a summary. Show details opens the request exactly as it will be run, with every setting, and Hide details folds it away again. Read it before approving a run whose settings matter to you. Once you have chosen, the buttons go and the card keeps a record of the outcome: Approved, Approved, and allowed for the rest of this conversation, Declined, or No decision was made if the assistant was stopped while the card was still waiting.

You can also answer an approval card by typing. Whatever you write in the message box is taken as your instruction in place of the operation, so use chain B instead declines the run and redirects it in one step. While a decision is waiting the status reads Needs approval, and the panel brings itself to the front if it was hidden.

The Ask before switch

More › Ask before long or destructive operations turns the approval step on and off. It is ticked by default, and the setting is remembered between sessions.

Leave the switch on unless you have a reason to turn it off. With it off, a request such as start again clears the session at once, and a docking run starts as soon as the assistant decides the setup is complete. Always allow on a single card is the narrower choice: it covers one kind of operation, in one conversation.

Plans

For a task of several steps, the assistant first writes a plan and shows it as a card, then updates the card as it goes. The count at the top right, such as 2 of 5, is how many steps are complete.

A plan card with every step completed
A plan card at the end of a task: the counter reads 3 of 3 and every step carries a tick. While work is in progress the step in hand is shown in bold and the steps still to come are listed beneath it, so you can see where a long task has got to.

A plan is a statement of intent, not a commitment you have to accept. If a step is not what you want, stop the assistant and say so, or simply tell it what to change when it next pauses.

Questions it asks you

Where a decision is properly yours and has no sensible default, the assistant asks. Typical cases are which of several comparable structures to use, which chain carries the site you care about, and which candidate compounds to dock. For everything else it picks the standard choice and tells you which it picked.

A question card with options
A question card. Each option has a line explaining it, and the option the assistant recommends is listed first and marked.
Part What it does
The optionsClick one to choose it. The hint under the list reads Choose one or Choose any that apply, depending on the question.
Other: type your own answerA line for an answer that is not among the options.
SubmitSends your choice.
SkipSends no choice, and the assistant carries on as best it can.

Typing in the message box and pressing Enter also answers the question. While a question is waiting the status reads Needs your answer. Afterwards the card records what happened, as Answered: followed by your choice, Skipped, or Not answered if the assistant was stopped before you replied, so the conversation shows later which decisions were yours.

Stopping it

While the assistant is working, the send button is a stop button. Press it, or press Esc with the cursor in the message box. The assistant stops where it is, the conversation records Stopped., and what it had already done stays done. A reply that was stopped part way is marked Stopped, and one that was cut off before it finished is marked Interrupted, so an incomplete answer is never mistaken for a finished one.

Stopping the assistant does not stop a docking run. A docking job or a validation that is already running carries on in the background after you stop the conversation. To stop the job itself, use Stop in step 5 of the Docking Panel, or ask the assistant to stop the docking run. Ligands that have already finished keep their results.

The assistant also stops by itself if a single request has taken a very large number of steps, and says so. Send a message to let it continue.

Typing while a job runs

A docking run can take a long time, and the conversation does not have to wait for it. While the assistant is waiting on a docking job or a validation, the message box reads The job runs in the background. Type to ask something meanwhile..., and anything you send is answered straight away. The job continues, the assistant follows its progress, and it reads the results once the job has finished.

The round button follows what you are doing. With the message box empty it stays Stop (Esc), and as soon as you type it becomes Send (Enter), so sending a question during a run does not stop anything.

The session itself is busy during a docking run, so some requests have to wait until the job ends. The receptor cannot be prepared again, ligands cannot be added or removed, the binding site cannot be defined, the docking mode cannot be changed, flexible, constraint or covalent docking cannot be set up, a validation cannot be started, a project cannot be opened and the session cannot be cleared. The assistant tells you when a request was refused for this reason. Ask again once the run has finished, or stop the run first.

The panel while a docking run is in progress
The panel during a docking run. The status in the header names the job, the last row of the conversation reports its progress, the message box invites you to carry on typing, and the send button has become the stop button.

What it can do

The tables below list everything the assistant can do in the application and everything it can look up. If a request falls outside them, it will say that it cannot do it instead of pretending.

Set up and run docking

Task What it covers
Fetch a structureA Protein Data Bank entry by its identifier, or a predicted model by its UniProt accession, downloaded and shown in the viewer.
Open a structure fileA file on disk that you name or attach, in any of the structure and small molecule formats the application reads.
Inspect a structureChains and residue counts, bound small molecules, waters, metal ions and the candidates for the co-crystallised ligand.
Prepare the receptorStep 1: which chains to keep, removal of waters and other bound molecules, hydrogens and charges. It uses the application's defaults unless you say otherwise, and can keep a catalytic metal or the waters near the ligand. You can also name the pH, the charge model, how hydrogens are handled and whether non-standard residues are removed, which is worth doing when your system needs something other than the defaults.
Add and remove ligandsStep 2: from a line notation string, a compound name or identifier looked up in PubChem, a Protein Data Bank ligand code, the co-crystallised ligand of the receptor, or files. Each ligand is built in three dimensions, protonated and minimised. Up to 50 can be added in one request. On request it can skip the minimisation, use the UFF force field in place of MMFF94 for a compound MMFF94 cannot handle, and replace the current ligand list instead of adding to it.
Define the binding siteStep 3: a box around the co-crystallised ligand, a box around residues you name, an explicit centre and size, or the whole protein for blind docking. State the padding if you want more or less room around the ligand or the residues than the default gives.
Validate the binding siteThe re-docking validation, then, if you ask, adoption of the box that passed. Needs your approval.
Change the settingsStep 4: scoring function, exhaustiveness, number of binding modes, energy range and processor cores. Asking for the Swift, Precise or Rigorous preset by name is the quickest way to set search effort, and any single value you state overrides the preset.
Set up a specialised modeFlexible side chains, named or chosen automatically near the ligand; constraints of each supported kind; and the covalent attachment read from the deposited structure. Each one switches the docking mode for you.
Run dockingStep 5: every prepared ligand in one batch. Needs your approval. It can also report how far a job has got, and stop it.
Manage the projectSave the project, open a saved one, or start a new empty one. Opening and starting new need your approval, because they replace the session.

Analyse results

Task What it covers
Read the resultsThe docked ligands ranked by best score, with the score and the two RMSD columns of each pose, as in the pose table.
Show a poseLoads a chosen pose of a chosen ligand into the viewer inside the receptor and draws its interactions.
Analyse interactionsHydrogen bonds, salt bridges, hydrophobic contacts, aromatic stacking, cation to aromatic contacts, halogen bonds, metal coordination, water bridges and clashes, with the residues, atoms and distances, drawn in the viewer and listed in the Interactions panel.
Compute ligand propertiesFormula, molecular weight, heavy atom count, hydrogen bond donors and acceptors, rotatable bonds and a rule of five check for the ligands in the session.
Export the results tableEvery pose of every docked ligand as a CSV file in the reports folder of the workspace.
Read a log or list filesThe text of a docking log or similar file, and a listing of what the workspace holds. Useful when you ask why a run failed.

Drive the 3D viewer

Task What it covers
Change the representationAny of the ten styles in The 3D viewer. The atom based styles can be applied to part of the structure, such as the ligand or the residues around it.
Change the colouringA colouring scheme, or a single colour for a chosen set of atoms.
Show, hide and isolateShow or hide a set of atoms, or show only that set, which is how to isolate a pocket.
Select, centre and labelSelect atoms by chain, residue, name or distance from the ligand, centre the view on them, and add or remove residue labels.
Set the sceneBackground colour, waters, hydrogens, the grid box, bonds, the surface type and the element colour palette.
Control the interaction displayWhich contact types are drawn, their lines, distances and labels, the pocket surface, and the reduced scenes meant for figures.
MeasureA distance, an angle or a dihedral between atoms you describe, drawn in the viewer.
Tidy up and undoClear measurements, labels and the selection, and undo or redo recent changes to the view.
Take a screenshotA PNG of the view, saved in the screenshots folder of the workspace and shown in the conversation. The picture is framed for the capture and your own view is left as it was. The image is 1600 by 1200 pixels unless you ask for another size, which a journal figure may need. The framing is chosen automatically, or you can ask for the whole structure, the ligand and its pocket, the current selection, or the view exactly as it is on screen.

Look things up

The assistant looks facts up in public databases instead of recalling them, and cites what it found with a link. The start screen names most of the sources it can reach. The table below is the full list.

Subject Sources What it can find
StructuresRCSB PDB, AlphaFoldEntries for a target, the details of an entry, the ligands bound in it, and whether a predicted model exists.
Binding sitesPDBeThe annotated binding sites of an entry: for each bound molecule, the residues that contact it. Useful for choosing which ligand or which residues should define the box.
ProteinsUniProtThe protein behind a name or a gene, with its function and annotations.
TargetsOpen TargetsA summary of a drug target, including its disease associations and known drugs.
BioactivityChEMBL, BindingDBMeasured activities of compounds against a target, which is how to assemble a set of known actives to dock.
ChemistryPubChem, ChEMBLA compound by name or identifier with its properties, and compounds similar to one you have.
LiteraturePubMed, Europe PMCPapers on a subject and their abstracts. Europe PMC also covers preprints and patents, so ask for those when the published literature is thin.
CitationsCrossrefThe full details of a citation from its DOI or its title, which is how a reference in a report is checked and completed.

Write reports

On request the assistant writes a study report from the live session and opens it. The application assembles the facts itself, so the numbers in the report are the numbers in the session, and the assistant contributes the narrative: the summary, the objective, the discussion, the conclusions and the literature references.

Aspect Detail
FormatsPDF, which is the default, a Word document, an Excel workbook holding every pose and interaction, HTML, or all four at once.
ContentsA cover with the key results, a table of contents, materials and methods, the re-docking validation with the crystal and re-docked poses superimposed, the ranking of every docked ligand, a section for each of the top ligands with its poses, a 3D figure, a 2D interaction diagram and an interaction table, a comparison of interactions across ligands, limitations and references. It also carries a score chart, a capture of the current 3D view, the computed properties of the ligands, references for the methods used, and an appendix listing the data files, so a reader can trace every figure back to its source.
OptionsSay so in the request if you want a subtitle, extra sections of your own, or a confidentiality line in the footer for work that is not to be circulated. You can set how many of the top ligands get a detailed section, which is ten unless you say otherwise, leave out the figures or the capture of the 3D view for a quicker, smaller report, and ask for the report not to be opened when it is done.
FiguresCaptured from the viewer with its current display settings. Style the view first if you want a particular look. The viewer shows each pose briefly while it is captured and is then put back as it was. The figures are also saved as PNG files beside the report.
Where it goesThe reports folder of the project workspace. A report is named docking_report_ followed by the date and time it was written, with its figures in a folder beside it, so successive reports never overwrite one another. The activity card lists the file with Open and Show in folder.

Show you where a control is

Task What it covers
Point at part of the windowA pulsing outline with a short caption, drawn for a few seconds around the thing in question: the Docking Panel, any of its steps or buttons, the viewer, a panel, the toolbar, the menu bar or the status bar. A hidden panel is opened first.
Show or hide a panelBrings a panel to the front, or puts it away.
Open a window for youOpens a dialog for you to work in by hand: receptor, ligands, binding site, settings, validation, the three mode pickers, the sketcher, the 2D diagram, the contact map, the Ramachandran plot, pose clustering or preferences. The assistant does not see what you do in it until your next message.
Close windowsCloses windows that are still open when you no longer need them.
The Co-Scientist outlining a step of the Docking Panel
Asked where the exhaustiveness is changed, the assistant has drawn an outline around step 4, Settings, in the Docking Panel, with a caption beneath it, and explains in the conversation what the step holds.

Every operation, by area

The sections above describe what the assistant can do in terms of the task. This is the complete list, named as the activity cards name each operation while it runs, so that an entry you see in a card can be found here. The list is produced from the application itself each time this manual is built, so it is always the full set for the version named at the foot of the page.

Area Operations
ReportWrite report
ViewerChange style, Change colour, Show or hide atoms, Select atoms, Focus view, Label residues, Background, Display options, Interaction display, Measure, Clear annotations, Undo, Screenshot
InterfacePoint at interface, Show panel, Open window, Close windows
SessionRead session state, New project, Open structure file, Save project, Open project, List workspace files, Read text file
StructuresFetch structure, Inspect structure, Prepare receptor, Search the PDB, Read a PDB entry, Look up a PDB ligand, Read binding sites, Find an AlphaFold model
LigandsAdd ligands, Remove ligands
Binding siteDefine binding site, Use validated box
DockingDocking settings, Docking mode, Flexible residues, Docking constraints, Covalent docking, Run docking, Stop docking, Re-docking validation, Job status
AnalysisDocking results, View pose, Analyse interactions, Ligand properties, Export results
ProteinsSearch UniProt, Read a UniProt entry
LiteratureSearch PubMed, Read PubMed abstracts, Search Europe PMC, Look up a citation
BioactivitySearch ChEMBL targets, Read ChEMBL bioactivities, Read BindingDB ligands
ChemistryRead a ChEMBL molecule, Look up a PubChem compound, Find similar compounds
TargetsSummarise a drug target

Worked examples

Each of these is a single message. They are written the way the assistant handles best: the goal, the system, and anything you have already decided.

You type What happens
Fetch 1HSG, prepare it as the receptor and define the binding site around its co-crystallised ligand.The structure is downloaded and shown, prepared with the default options, and boxed around its bound inhibitor. Steps 1 and 3 of the Docking Panel turn green.
Run a re-docking validation of the current binding site and tell me whether it passes.An approval card appears. After you approve, the validation runs and the answer gives the verdict and the RMSD to the crystal pose.
Add ibuprofen, naproxen and celecoxib as ligands and dock them at exhaustiveness 16.The three compounds are looked up by name, built and prepared, the setting is changed, and an approval card asks before the run starts.
Which residues does the best pose of the top ligand contact? Show them as sticks and label them.The pose is loaded, its interactions are detected and listed in the answer with distances, and the view is restyled.
Find potent inhibitors of this target with measured activities and suggest three worth docking.The bioactivity databases are searched, and the answer is a short table of compounds with their activities and links to the records. Nothing in the session changes until you ask.
White background, cartoon receptor, ligand as sticks, interactions with residue labels, then take a screenshot.The view is set up step by step and the image appears in the conversation.
Write a PDF report of this study, and a Word copy.The report is assembled from the session in both formats and opened.
Where do I set which side chains are flexible?A short answer, and the assistant can outline the relevant step of the Docking Panel on screen.
The window after the Co-Scientist has docked a ligand
The end of a docking request. The answer gives the score of the best pose, lists the hydrogen bonds and hydrophobic contacts with their distances, and closes with its own caveats and a suggested next step, while the viewer shows the pose it is describing.

Phrasing requests well

Do this Because
Name things exactly: the structure identifier, the chain, the residue with its number, the compound.The assistant does not guess identifiers. Given a vague name it has to search and may have to ask you, which costs a turn.
Say how far to go. Set it up but do not run it is a complete instruction.It does what was asked and then stops and offers the next step. It does not carry on through a whole workflow you did not request.
State the decisions you have already made: which chain, what exhaustiveness, which ligand defines the site.Anything you do not specify is given the standard default. That is usually right, but it is your study.
Ask for one study per conversation, and start a new conversation for a new subject.The whole conversation accompanies each request, so a long, mixed conversation is slower and uses the allowance faster.
Ask it to explain or justify. Why chain A? is a good question.The reasoning is often more useful than the result, and it is where a wrong assumption shows.
Correct it plainly when it is wrong.It reads the session afresh with every message and will act on the correction.

Its limits

The footer of the panel says The Co-Scientist can make mistakes. Check important results. These are the mistakes worth guarding against.

Limit What to do about it
A stated fact can be wrong or out of date, including a measured activity, a resolution or a citation.Follow the link it gives and read the source. Treat a fact given without a link as unverified.
A docking score is an estimate, and the assistant's interpretation of it is an interpretation.Judge poses by their interactions and by the agreement between the top poses, as The pose table explains. Compare candidates with the re-docked crystal ligand under the same settings.
A default it chose may not suit your system.Open the row in the activity card and read Input. The chains, the padding and the settings actually used are all there.
It sees the session through a summary, not through your eyes.If it describes the view or the results in a way that does not match the screen, tell it what you see.
A long reply can be cut short, and a very long conversation can be shortened to fit. The conversation says so when either happens.Ask it to continue, or start a new conversation and restate what matters.
It will not help with work outside its subject, and it will not help design agents intended to cause harm.This is deliberate and is not something a rephrased request will change.
Check anything you intend to rely on. A result that will go into a report, a paper or a decision about what to synthesise should be confirmed independently: the validation RMSD in the validation report, the contacts in the Interactions panel, the literature in the papers themselves. The assistant is quick and well read, and neither of those is the same as being right.