• Docs »
  • BROOD Graphical Interface

BROOD Graphical Interface

Overview

vBROOD is the graphical interface that ships with BROOD. It gives access to all the command-line features as well as some GUI-only features, such as query and filter editing, and placing constraint and color atoms.

vBROOD allows users to interactively design filters to limit the scope of the database search or produce results with properties in an expected range. This can improve both the run-time performance and the quality of the output structures.

Upon completion, BROOD clusters the result molecules. vBROOD presents the cluster heads for viewing; the full clusters can be explored in VIDA (see Viewing Results in VIDA).

Most BROOD options can be changed from within vBROOD. vBROOD can easily run BROOD in multiprocessor mode. vBROOD cannot, however, run BROOD across a cluster.

Tasks in vBROOD

Task Screen

The vBROOD task screen

vBROOD offers five tasks to help run BROOD:

  • Build and Run: Create a query and immediately start a BROOD run.
  • Build a New Query: Create and edit a query to save and later send to a BROOD run.
  • Run BROOD: Run BROOD with a previously created filter and query.
  • Filtering: Create filters for BROOD and post-filter hitlists from previous runs.
  • View Results: Browse results and launch the BROOD interface in VIDA.

Build and Run

Build and Run is the most direct way to run BROOD. This feature walks users through the entire process of constructing a query, setting up a BROOD run, and browing results.

The Build and Run wizard consolidates the Build a New Query and Run BROOD steps. However, the Query Selection page in the Run BROOD wizard is bypassed, and queries will be saved only in the Run directory. Filter building is also bypassed, although a previously built filter may be chosen.

Loading a molecule

The first step in creating a BROOD query is to load or create a source molecule. The molecule can be loaded from a file, entered by name, or sketched in the sketcher.

  • To load a molecule from a file, either click the folder in the Molecule text entry box or choose a recently loaded molecule from the drop-down menu, which can be accessed from the arrow in the text entry box.
  • To enter a molecule by name, type a structure name or a SMILES string in the text entry box. The 2D display will show a molecule if the entry is valid.
  • To sketch a new molecule, click the + in the text entry box. This opens the sketcher for input. Sketch a molecule and click OK when you are satisfied with the sketch.
Loading a Molecule

Loading a molecule

A protein can be loaded to provide a bump-check for generated results, although protein chemistry is not used as part of the score. You can also specify a selection protein, which requires a protein atom to be close to the query as a simplistic screen for selectivity.

Below the protein text entry boxes, vBROOD displays the properties of the loaded molecule. Any properties that vBROOD determines might need attention are highlighted in red.

Selecting a fragment for replacement

After loading or creating a molecule, vBROOD will display the 2D structure. You must then select some portion of the molecule for replacement. You can select the fragment to be replaced in two ways:

  • Click one or more of the highlighted fragments or
  • Select a fragment by lassoing it (holding the Left Mouse button down and circling the fragment).
Fragment-based selection Lasso selection
Fragment-based selection Lasso selection

Fixing problems

Some molecules may need additional fixes for problems found when they are loaded or selected. vBROOD highlights any problematic atom or bond and displays a message in the lower-right corner. If the message is red, the problem must be fixed before you can continue to build the query. Messages in yellow can be ignored, but usually should be addressed as they may lead to unexpected behaviors.

The following are examples of some problems and their fixes .

Unspecified stereochemistry

BROOD requires the specification of certain types of stereochemisty. Ignoring this problem can result in issues with coordinate generation or with property filtering. To fix unspecified stereochemistries, right-click on the red highlighted atom or bond and select Set Chirality or Set Bond Stereo and choose the appropriate stereochemistry.

Fixing bond stereo

Fixing bond stereo

Broken double bonds

BROOD does not allow double bonds to be broken by selection. To correct this problem, either click Select Bond or redo the selection.

A double bond broken by selection

A double bond broken by selection

Partially selected rings

Broken aliphatic rings can be ignored (but will always be closed), but broken aromatic rings must be fixed. To do this, either click Select Ring button or redo the selection.

A ring broken by selection

A ring broken by selection

More than three attachment points

BROOD’s default databases have between one and three attachment points. Unless you are using a custom fragment database, BROOD will not produce any results when you use a query with four or more attachments. Redo the selection so that it has between one and three attachment points or generate and use a non-default database that includes fragments with four attachment points.

A selection resulting in 4 attachment points

A selection resulting in four attachment points

Overlapping attachment points

Selecting two atoms that are each bonded to a third, unselected atom results in two attachment points overlapping. To correct this, click Fix or redo the selection.

A selection resulting in overlapping attachment points

A selection resulting in overlapping attachment points

No Selection

vBROOD requires you to select some fraction of the molecule or it will not continue. To fix this, select a fragment of the molecule.

Edit fragment screen

Edit fragment screen

Once a molecule has a valid selection and all problems have been resolved, the Next button will be enabled. Click Next to advance to the Edit Fragment step.

Editing fragments

The Edit Fragment step allows users to edit some aspects of the replacement query. You can add and remove color atoms, add and remove constraints, or remove atoms in the query. This step also displays the query structure in 3D as well as the attachment vectors as R-group atoms. Color atoms are displayed as large spheres patterned and colored according to the color atom type. Constraint atoms are displayed as colored and patterned rings with a diameter corresponding to the diameter of the constraint.

The Fragment Editor provides five tools for editing a query, shown as icons on the left side of the 3D window:

  • Select. Selects atoms. This can be used to select a group of atoms for deletion.
  • Add Color Atom.A drop-down menu is provided (click on the arrow on the right of the icon) to select the color atom type.
  • Add Constraint Atom. A drop-down menu is provided to select the constraint type.
  • Eraser. Can erase an atom, color atom, or constraint.
  • Delete Selected. Deletes all selected atoms.

If the query includes a protein, it is also possible to toggle the visibility of the protein with the Show Protein and Hide Protein buttons.

Adding a color atom

Add Color Atom

Add Color Atom

Color atoms allow users to specify desired chemistry at specific places on the fragment. Adding a color atom to a molecule is simple:

  1. Select a color atom type from the Color Atom menu in the Fragment Editing toolbar.
  2. Click an atom.

Either color atoms or molecular atoms can be selected. Multiple color atoms placed in the same location are displayed as slices of the same color atom sphere. By placing the same type of color atom at the same location, color atoms may be weighted to increase their influence on the score.

To place a color atom in between one or more atoms, hold the Shift key while clicking additional atoms. The color atom will be placed at the center of mass of the selected group.

Adding a constraint

The constraint menu A constraint
The constraint menu A constraint

A constraint is much like a color atom in that it represents desired chemical features. Unlike a color atom, however, a constraint is a requirement, not a component of the score. Adding a constraint to a molecule is largely the same as adding a color atom:

  1. Select a constraint type from the constraint menu in the Fragment Editing toolbar.
  2. Click an atom. Multiple constraints in the same location will be displayed as segments of the same ring.

As with color atoms, to place a constraint in between one or more atoms, hold the Shift key while clicking additional atoms. The constraint will be placed at the center of mass of the selected group.

The custom constraint dialog The custom SMARTS dialog
The custom constraint dialog The custom SMARTS dialog

Custom constraints can also be defined with user-supplied SMARTS patterns. To define a new constraint type, select Add Custom Constraint. The Add Custom Constraint dialog prompts for a constraint name, a constraint SMARTS pattern, and a radius. SMARTS patterns can be either typed in the SMARTS text edit or selected from the SMARTS dialog by clicking the + button in the SMARTS text edit.

Once these steps have been completed, click Next to progress to the next page.

Selecting a filter

Choose a filter

Choose a filter

A pre-filter can be applied to limit the BROOD search and shorten the run time. vBROOD provides a built-in Druglike filter; users can also build additional filters. To use a filter, select one from the list or open a previously saved filter. See Filtering for more information on creating a filter.

To open a previously saved filter:

  1. Click on the Open option in the list. This brings up a dialog that can be used to select a filter.
  2. Select a filter file and click Open. This adds and selects a new entry in the list.

Alternatively, you can select filters from the Recents menu, which is accessed by clicking on the Down Arrow in the Open option under Loaded Filters. (If you are using BROOD for the first time, this folder may be empty.)

Selecting a filter will display the filter values for the given properties in the Filter Values box below the filter list. When you are satisfied, click Next to continue to Setup BROOD.

Setting up BROOD

Run options

Run options

The next step in running BROOD is choosing the run parameters. Most options correspond directly to a command-line option. Hovering with the mouse cursor over most elements in the interface provides a brief description of the option as well as the command-line flag it represents.

The multiprocessor options, found in the Quick Options section, are particularly useful. These options allow you to run multiple BROOD instances using OpenMPI on the same machine as vBROOD. This allows BROOD to make use of additional processors if they are available.

For further information on individual options, please see the section Command-Line Interface.

When all options are set, click Run to start the BROOD run and advance to the Run BROOD page.

Run BROOD

A run in progress A completed run
A run in progress A completed run

After Run is selected, the screen will switch to display a 2D hitlist, the BROOD Output window, and the Run Status window. This display will dynamically update as the run progresses.

  • The Hitlist shows the current cluster heads from the database.
  • The Run Status window on the left shows information about how many fragments have been processed, how many were actually scored against the query, and how many were eliminated.
  • The Output window at the bottom displays the output of the BROOD run as if it were run from the command line. This can be switched to show a spreadsheet of the top results by using the buttons on the right side of that panel.
  • At the bottom right of the vBROOD window is a progress bar and a Stop button for aborting the run.

As the run progresses, the top results are displayed in the 2D hitlist and the results spreadsheet continues to update. Both the spreadsheet and the 2D hitlist provide scrollbars for browsing the hitlist. Clicking on a 2D depiction highlights the same row in the spreadsheet and vice versa.

After a run completes, the buttons Open in VIDA and Show on Disk will be displayed and enabled. Clicking on Open in VIDA opens VIDA with the BROOD Results Viewer tool loaded (see Viewing Results in VIDA). Clicking Show on Disk opens a window displaying the directory containing the results of the run. If the run did not complete successfully, BROOD displays a dialog box and the Output window at the bottom shows the Log view. Scanning the log may provide some indication of the problem.

Click Browse Results to bring up the list of all runs for the current session. See View Results for more information.

Build a New Query

The process for building a query is much the same as that of Build and Run:

  1. Load a molecule.
  2. Select a fragment.
  3. Modify the fragment to be replaced.

The difference is that the workflow stops after editing the fragment and allows you to save the query.

Loading a molecule

The first step in creating a BROOD query is to load or create a source molecule. The molecule can be loaded from a file, entered by name, or sketched in the sketcher.

  • To load a molecule from a file, either click the folder in the Molecule text entry box or choose a recently loaded molecule from the drop-down menu, which can be accessed from the arrow in the text entry box.
  • To enter a molecule by name, type a structure name or a SMILES string in the text entry box. The 2D display will show a molecule if the entry is valid.
  • To sketch a new molecule, click the + in the text entry box. This opens the sketcher for input. Sketch a molecule and click OK when you are satisfied with the sketch.
Loading a Molecule

Loading a molecule

A protein can be loaded to provide a bump-check for generated results, although protein chemistry is not used as part of the score. You can also specify a selection protein, which requires a protein atom to be close to the query as a simplistic screen for selectivity.

Below the protein text entry boxes, vBROOD displays the properties of the loaded molecule. Any properties that vBROOD determines might need attention are highlighted in red.

Selecting a fragment for replacement

After loading or creating a molecule, vBROOD will display the 2D structure. You must then select some portion of the molecule for replacement. You can select the fragment to be replaced in two ways:

  • Click one or more of the highlighted fragments or
  • Select a fragment by lassoing it (holding the Left Mouse button down and circling the fragment).
Fragment-based selection Lasso selection
Fragment-based selection Lasso selection

Fixing problems

Some molecules may need additional fixes for problems found when they are loaded or selected. vBROOD highlights any problematic atom or bond and displays a message in the lower-right corner. If the message is red, the problem must be fixed before you can continue to build the query. Messages in yellow can be ignored, but usually should be addressed as they may lead to unexpected behaviors.

The following are examples of some problems and their fixes .

Unspecified stereochemistry

BROOD requires the specification of certain types of stereochemisty. Ignoring this problem can result in issues with coordinate generation or with property filtering. To fix unspecified stereochemistries, right-click on the red highlighted atom or bond and select Set Chirality or Set Bond Stereo and choose the appropriate stereochemistry.

Fixing bond stereo

Fixing bond stereo

Broken double bonds

BROOD does not allow double bonds to be broken by selection. To correct this problem, either click Select Bond or redo the selection.

A double bond broken by selection

A double bond broken by selection

Partially selected rings

Broken aliphatic rings can be ignored (but will always be closed), but broken aromatic rings must be fixed. To do this, either click Select Ring button or redo the selection.

A ring broken by selection

A ring broken by selection

More than three attachment points

BROOD’s default databases have between one and three attachment points. Unless you are using a custom fragment database, BROOD will not produce any results when you use a query with four or more attachments. Redo the selection so that it has between one and three attachment points or generate and use a non-default database that includes fragments with four attachment points.

A selection resulting in 4 attachment points

A selection resulting in four attachment points

Overlapping attachment points

Selecting two atoms that are each bonded to a third, unselected atom results in two attachment points overlapping. To correct this, click Fix or redo the selection.

A selection resulting in overlapping attachment points

A selection resulting in overlapping attachment points

No Selection

vBROOD requires you to select some fraction of the molecule or it will not continue. To fix this, select a fragment of the molecule.

Edit fragment screen

Edit fragment screen

Once a molecule has a valid selection and all problems have been resolved, the Next button will be enabled. Click Next to advance to the Edit Fragment step.

Editing fragments

The Edit Fragment step allows users to edit some aspects of the replacement query. You can add and remove color atoms, add and remove constraints, or remove atoms in the query. This step also displays the query structure in 3D as well as the attachment vectors as R-group atoms. Color atoms are displayed as large spheres patterned and colored according to the color atom type. Constraint atoms are displayed as colored and patterned rings with a diameter corresponding to the diameter of the constraint.

The Fragment Editor provides five tools for editing a query, shown as icons on the left side of the 3D window:

  • Select. Selects atoms. This can be used to select a group of atoms for deletion.
  • Add Color Atom.A drop-down menu is provided (click on the arrow on the right of the icon) to select the color atom type.
  • Add Constraint Atom. A drop-down menu is provided to select the constraint type.
  • Eraser. Can erase an atom, color atom, or constraint.
  • Delete Selected. Deletes all selected atoms.

If the query includes a protein, it is also possible to toggle the visibility of the protein with the Show Protein and Hide Protein buttons.

Adding a color atom

Add Color Atom

Add Color Atom

Color atoms allow users to specify desired chemistry at specific places on the fragment. Adding a color atom to a molecule is simple:

  1. Select a color atom type from the Color Atom menu in the Fragment Editing toolbar.
  2. Click an atom.

Either color atoms or molecular atoms can be selected. Multiple color atoms placed in the same location are displayed as slices of the same color atom sphere. By placing the same type of color atom at the same location, color atoms may be weighted to increase their influence on the score.

To place a color atom in between one or more atoms, hold the Shift key while clicking additional atoms. The color atom will be placed at the center of mass of the selected group.

Adding a constraint

The constraint menu A constraint
The constraint menu A constraint

A constraint is much like a color atom in that it represents desired chemical features. Unlike a color atom, however, a constraint is a requirement, not a component of the score. Adding a constraint to a molecule is largely the same as adding a color atom:

  1. Select a constraint type from the constraint menu in the Fragment Editing toolbar.
  2. Click an atom. Multiple constraints in the same location will be displayed as segments of the same ring.

As with color atoms, to place a constraint in between one or more atoms, hold the Shift key while clicking additional atoms. The constraint will be placed at the center of mass of the selected group.

The custom constraint dialog The custom SMARTS dialog
The custom constraint dialog The custom SMARTS dialog

Custom constraints can also be defined with user-supplied SMARTS patterns. To define a new constraint type, select Add Custom Constraint. The Add Custom Constraint dialog prompts for a constraint name, a constraint SMARTS pattern, and a radius. SMARTS patterns can be either typed in the SMARTS text edit or selected from the SMARTS dialog by clicking the + button in the SMARTS text edit.

Once these steps have been completed, click Next to progress to the next page.

Finishing up

After editing the query, either click Save or Save & Run. Save will ask for the file name and return you to the task selection screen. Save & Run will ask for a file name, save, and then move on to the Run BROOD task.

Run BROOD

vBROOD runs the BROOD command-line application using a query. It can run BROOD on multiple processors, provide access to the BROOD command-line options, display the output of the command line in a log window, and display the best fragments found as the run progresses.

Loading a query

Loading a query

Loading a query

The first step to running BROOD is to load or select a query.

  • Previously build queries appear in the query list.
  • Queries can be loaded by clicking the Open item or selecting a recently loaded query from the Recents menu.
  • If the query did not have an associated protein, clicking on the Open folder in the Protein text entry will allow you to add one.

After a query is selected, it is displayed in the 3D window. Once it is loaded, clicking Next will take you to Selecting a filter.

Selecting a filter

Choose a filter

Choose a filter

A BROOD run can use a filter to limit the BROOD search and shorten the run time. vBROOD provides a built-in Druglike filter; users can also build additional filters. To use a filter, select one from the list or open a previously saved filter. See Filtering for more information on creating a filter.

To open a previously saved filter:

  • Click the Open item in the list. This will bring up a dialog that can be used select af filter.
  • Select a filter file and click Open. This will add and select a new entry in the list.

Alternatively, you can select a filter from the Recents menu. Selecting a filter will display the filter values for the given properties in the Filter Values box below the filter list. When you are satisfied, click Next to continue to Setup BROOD.

Setup BROOD

Run options

Run options

The next step in running BROOD is choosing the run parameters. Most options correspond directly to a command-line option. Hovering with the mouse cursor over most elements in the interface provides a brief description of the option as well as the command-line flag it represents.

The multiprocessor options, found in the Quick Options section, are particularly useful. These options allow you to run multiple BROOD instances using OpenMPI on the same machine as vBROOD. This allows BROOD to make use of additional processors if they are available.

For further information on individual options, please see the section Command-Line Interface.

When all options are set, click Run to start the BROOD run and advance to the Run BROOD page.

Run BROOD

A run in progress A completed run
A run in progress A completed run

After Run is selected, the screen will switch to display a 2D hitlist, the BROOD Output window, and the Run Status window. This display will dynamically update as the run progresses.

  • The Hitlist shows the current cluster heads from the database.
  • The Run Status window on the left shows information about how many fragments have been processed, how many were actually scored against the query, and how many were eliminated.
  • The Output window at the bottom displays the output of the BROOD run as if it were run from the command line. This can be switched to show a spreadsheet of the top results by using the buttons on the right side of that panel.
  • At the bottom right of the vBROOD window is a progress bar and a Stop button for aborting the run.

As the run progresses, the top results are displayed in the 2D hitlist and the results spreadsheet continues to update. Both the spreadsheet and the 2D hitlist provide scrollbars for browsing the hitlist. Clicking on a 2D depiction highlights the same row in the spreadsheet and vice versa.

After a run completes, the buttons Open in VIDA and Show on Disk will be displayed and enabled. Clicking on Open in VIDA opens VIDA with the BROOD Results Viewer tool loaded (see Viewing Results in VIDA). Clicking Show on Disk opens a window displaying the directory containing the results of the run. If the run did not complete successfully, BROOD displays a dialog box and the Output window at the bottom shows the Log view. Scanning the log may provide some indication of the problem.

Click Browse Results to bring up the list of all runs for the current session. See View Results for more information.

Filtering

The vBROOD filter interface

The vBROOD filter interface

vBROOD provides tools for creating filters for BROOD runs and for post-filtering hitlists. The filtering tool displays the distributions of the values of various properties both pre- and post- filter. The values can be adjusted numerically or visually. The various properties are available in three separate tabs:

  • Physical properties
  • Synthetic accessibility
  • Derived properties

Building a filter for running BROOD and filtering a hitlist are much the same process, though the initial setup is a bit different (see below).

You can select the desired path by selecting the appropriate radio button: Results for filtering a hitlist or Database for building a BROOD run filter.

For details on specific property filters, see Property Selection.

The Filter window

The Filter window consists of 12 histograms detailing various medicinal chemistry properties. While filtering, each histogram displays two lines, one red and one blue. The red line indicates the pre-filter distribution. The blue line indicates the distribution of the remaining fragments after all filters have been applied. Additionally, when creating a BROOD Run filter, the histograms will display a red vertical line at the value for the query molecule.

The large histogram at the top is interactive and is a reproduction of one of the smaller 11 histograms in the bottom half of the screen. To set the property to be displayed in the primary histogram, click on one of the smaller histograms.

The top histogram is interactive and has one or two draggable black lines capped with Left and Right Arrows. Clicking and dragging one of these lines can set the minimum or maximum value for the given property. Changing this value will also update the histograms of all the other properties to give an estimate of the distribution of the values remaining.

Filtering

A property histogram

A property histogram

Filter values can be set two ways: by typing a value or by dragging the filter line. To set by value, navigate to the page containing the property and adjust the appropriate control to set the value.

There is one Setup Filter page and three property pages. The Setup Filter page allows you to choose the type of filtering you want and to perform filter setup. The three property pages are Physical Properties, Synthetic Accessibility and Derived Properties. Each of these pages provides direct input of filter ranges by typing in exact values.

For details about specific property filters, see Property Selection.

Setting up a filter

The first page is the Setup Filter page that allows you to choose whether to build a run filter or to perform a hitlist filtering. It also displays how many fragments or molecules are remaining, and allows the current filter to be set to one of the two presets, Permissive and Druglike.

BROOD Run filter

Building a filter allows BROOD to quickly eliminate some fragments of the database without doing the 3D overlap. This can result in much shorter run times. The filter is built in the context of a query, though it may be used with any query. The values in vBROOD are not in the same reference frame as the values passed to BROOD. vBROOD combines query information to allow users to generate filters at the molecular scale rather than the fragment scale. When vBROOD calls BROOD, it translates the filter to fragment-based values by removing the query contribution.

To build a filter for BROOD:

  1. Select the Database radio button.
  2. Select a query. You can select a query from the query list, open a query from a file using the Open item in the query list, or load a recently opened query from the Recents menu.

Once a query has been selected, vBROOD will populate the histograms.

Hitlist filtering

Hitlists can also be filtered after a BROOD run:

  1. Select the Results radio button.
  2. Open a BROOD Results file by clicking on the Open folder.

After loading, the histograms will be populated with the values from the Results file. On the final page (Derived Properties), choose Save Hitlist to save your filtered hitlist to disk.

Filter presets

The Druglike preset filter sets the property filters to the following ranges:

  • Synthetic Accessibility => .1
  • Heavy Atom Count <= 30
  • Molecular Weight <= 500
  • Rotor Count <= 10
  • LogP <= 5.0
  • Polar Surface Area <= 150
  • Lipinski Donor Count <= 5
  • Lipinski Acceptor Count <= 10
  • Lipinski Failures <= 1
  • ABS >= .25
  • Fraction sp3 Carbons >= .3
  • Aromatic Freres Jacques <= 4
  • Egan egg is not required
  • Veber bioavailability is not required

The Permissive filter sets property ranges so all fragments through pass the filter.

View Results

Browsing results

Browsing results

The final wizard launches the Results Viewer. This displays a list of all BROOD runs since launching vBROOD. Selecting a single run displays the cluster heads from the hitlist file. It also allows you to locate the file on disk (using Show on Disk) and to launch the vBROOD Results Viewer. Finally, previously generated results saved on disk may also be loaded.

If the run was from the current session of vBROOD, the Log window will be populated with the output of BROOD. This includes detailed information regarding how the results were generated. Otherwise, it will be blank.

The vBROOD Results Viewer displays the cluster heads in 2D along with a spreadsheet containing medicinal chemistry properties and scores. The currently browsed run can be changed in the Results list box or by selecting the corresponding spreadsheet tab. Additional results can be loaded by selecting the Open Results... item in the list box or choosing Open Results... from the File menu and choosing a hitlist file. Results can be closed by clicking on the red X in the Results list.

Once a result hitlist is selected, you can browse the cluster heads via the spreadsheet or by scrolling the 2D window. Clicking on Open in VIDA will launch the vBROOD Results Browser for more full-featured exploration of the clusters (see Viewing Results in VIDA).

If a set of results came from a run in the current vBROOD session, the Log file may be displayed by clicking on the Log button in the lower right-hand corner. This displays the command-line output of BROOD and can be useful in diagnosing unexpected output.