Chem Biography Platform Usage Instructions

The Chem Biography (CB) application utilizes a web based interface. It is accessed via the main menu page, http://{server}/chembiography.php, with the server part of the address replaced by the name assigned to the computer server as part of the initial setup. While CB is designed to function across all common internet browsers, it is optimized for Firefox / Mozilla which can be freely downloaded; use of CB with Firefox is recommended.

Accessing the main menu page (Figure 1.1, “Chem Biography Main Menu”) provides access via web links (left panel) to the three primary components of the CB application: CB database searching, chemical registry, and biological data upload. Each of these components will be described in more detail below. Additionally, on the CB main page is a middle panel that provides predefined quick searches, by data type, of recently added data and a right panel allowing linking to the most recently uploaded biological results. One of the intentions of the CB architecture is for the user to always have facile access to the most recent data generated.

It is beneficial for all users to understand, at a basic level, how data are stored and managed with the CB system. The objective is a relatively simple system that nonetheless provides high flexibility and facile access to the data. The central principles employed are:

As mentioned above the chemical registry table defines the data architecture scaffold in CB. Five fields are mandatory and required: registry id, molecular weight, formula, chirality, and SMILES. Values for these fields are automatically computed by the application during a registration operation and are provided as part of the default CB setup. Other desired fields (notebook, chemist, etc.) may be added as needed as described in the administration section. Additionally, the format of registry id field (e.g. AB-1234, AB001234-1, AB-01234.1 etc.) is customizable. Chem Biography staff will work with you during administrative setup to define the format you desire, and what if anything your registry id might encode (for example a batch number or salt code).

Accessing the chemical registry presents the page show above Figure 2.1, “Chemical Registry Front Page”. A series of options are presented, each of which is accessed via the web link provided. At the top of the page is the option for registering a new molecule. Next are options for viewing, editing, or deleting, an already registered molecule; these options require entry of an existing registry ID in the "Registry Number" text box. The final two features are utilized to either upload supporting data files for a registered molecule or to use a registered molecule as a template for a new molecule registration.

Selection of this option presents the user with a web form to enter the appropriate data for a chemical registration. An example populated form is shown in Figure 2.1, “Chemical Registry Front Page”. At the left of the registry form is a chemical structure drawing tool (J2A chemical editor) which has been developed as part of the CB application (described below). In addition to the drawing tool the user will find a series of form fields. These fields are specified as part of the CB setup and will likely include components such as medicinal chemist, notebook page, project the compound was synthesized for, etc. The fields may also occur as any of the standard web form types (drop down menu, text field, check box, text area). Asterisks by a field name denote that the field is required for registration to proceed. A registry entry's accompanying fields and types are discretionary and shall be modified to suit your organization's needs during initial setup of your system.

Correct assignment of registry ID is an important step in research data management. The CB platform algorithmically performs this step following submission of the registry form. Several things go on “under the hood” to ensure appropriate assignment:

Following submission of the form a registry ID is provided as shown in Figure 2.3, “Example Registered Molecule”. Once this has occurred the user may then also choose to upload any supporting data (e.g. LCMS or NMR spectra) and these data will then be associated with the registered molecule and retrievable via an html link (as indicated by green text for the field name – Figure 2.4, “Upload Analytical Data Files”). Types of supporting data allowed are part of the registry setup.

Once a molecule is registered, it may be viewed or subsequently modified or deleted. From the main registry page, enter the ID and select the desired operation. Note that shortcuts in typing may often be used for convenience (e.g. entering 2 will be expanded to AB-002 or whatever the formal registry id format has been set to). Proceeding will pull up all compounds matching the registry id query. If a version is not specified (e.g. there are AB-0002.1 and AB-0002.2 but only AB-0002 is entered), then both possibilities are displayed. When editing or deleting, select the radio button (edit example is shown) above the desired entry and then the continue button at the bottom of the web page.

As noted and described above for new molecule registration, once a molecule is registered, supporting data may then be uploaded and linked to it. This feature is also available from the main registry page.

Often when working in a chemical series, multiple structurally related analogs are synthesized and they may also have common features such as project name. To facilitate entering of data and drawing, the template feature allows one to populate the new molecule registration form with all the data from a previously registered molecule (note that one useful feature of this function is assuring that related molecules are drawn in a standard orientation, thereby possibly facilitating SAR analysis). Once in the new registration from, change the fields that need to be edited (e.g. notebook page) and register as before. The molecule used as the template is in no way affected by this procedure.

All drawing is done via use of the left mouse button. After initiating the drawing tool the user will be either in a new molecule mode if no structure has previously been drawn or an edit molecule mode if a structure already exists. Once anything is drawn in the drawing panel, the user now transitions into edit molecule mode. The distinction between new and edit mode is that in edit mode one can only build off an existing atom or bond whereas in new mode a structure unconnected to any existing ones may be initiated and connections to existing molecules are deliberately prevented. A new unconnected structure may be added to existing ones at anytime via selection of the NEW option. During all drawing, a running account of atoms, bonds, molecular weight and formula (with both implicit and explicit hydrogens) is maintained.

Anytime an option is selected it will be highlighted in green. When building onto an existing molecule, two situations will consistently be encountered. One is when the cursor is over an existing atom indicating intent to modify or build off this atom (atom typing, bond addition, ring addition). Here the user will see a blue square, as shown, surrounding a particular atom indicating it is the current active atom. The second is when the cursor is over an existing bond (midpoint of the bond) indicating intent to modify or build off this bond (bond typing, fused ring addition). Here the user will see a blue circle over the midpoint of the bond.

Options are provided for drawing single, double, triple and chiral bonds. If initiating a new molecule, selection of one of the bond options and then clicking in the drawing panel will place the appropriate bond. If building onto an existing molecule and clicking an atom, a bond of appropriate type will be grown from the selected atom. Note that anytime a bond is being grown, the user can, instead of clicking and releasing in the drawing panel, hold the left mouse button down and drag the cursor. What this procedure will do is allow custom orientation of the bond as opposed to default grow rules (120 degree angles for single and double or 180 degree angles for triple bonds). Other particular features are:

Single Bond: clicking on an existing bond when the single bond option is selected will cycle that bond incrementally (double, triple, back to single).

Double bond: clicking on an existing double bond when the double bond option is selected will cause the “second” bond of the double bond to reorient its position to the opposite side of first bond. One use of this feature would be to alter the appearance of a bridgehead double bond in a polyaromatic ring system.

Chiral bond: Repeated clicking on an existing bond when the chiral bond option is selected will toggle that bond through 4 options comprising wedge up or down and direction of chirality.

Long distance bonds / connecting separate structures: To form a bond between two atoms that are outside the standard bond length, for example as might occur when connecting to distinct molecules or rendering a bycyclic ring or natural product, select the first atom but keep the left mouse pressed down and drag to the second atom (now highlighted by the blue square) and then release.

Standard rings from 3 to 8 atoms in size are available for use as templates. They may be used to build off an existing atom or fused onto an existing ring. For building off an existing atom, the atom must have no more than one current bond. The rings templates may also be used to initiate a structure when in new molecule mode.

A panel of standard medicinal chemistry atom types is provided for use in structure drawing. Additionally, a “wildcard” atom functionality is available to enable inputting any atom as needed. Select the desired atom type and then label the atom on the structure. The atom may be reverted to an implicit carbon by repeating this process (e.g. to turn an oxygen back to carbon, click on the O in the menu then click the oxygen in the structure). As noted, carbons are implicit but may be specifically labeled with the carbon from the menu. Hydrogen’s are normally calculated but may also be made explicit via labeling. To use the wildcard function, enter the desired type (do not use charges here – use the charge function below) in the wildcard atom text box and then click the update button. The wildcard atom will then be reflected in the menu (shown here as A in the figure above).

Charges are assigned via selecting the + or – menu objects and then clicking the desired atom in the drawing structure. Repeated clicking of the same atom will increment the formal charge to the magnitude desired. To reduce or remove a charge from an atom, select the opposite sign and click on the atom as many times as needed.

NEW: Draw a new molecule. Selection of the NEW option permits drawing of a structure disconnected from any already drawn structure. After selecting NEW option, immediately pick one of the drawing options and then click on an unoccupied portion of the drawing canvas to complete the action. Once the drawing is done, the NEW mode is automatically exited. This mode is the default when initiating the J2A chemistry editor and no molecule has been previously drawn.

CLR: Clear the drawing canvas. Selection of CLR removes all drawn structures from the canvas. It is a full delete and resets the drawing canvas to new molecule mode

DEL: Delete a bond or atom. After selecting the delete mode, click on specific atoms or bonds to delete them.

UND: Undo the last action. Selecting the undo mode cause the currently displayed structure(s) to revert to their state before the last drawing event.

When in edit mode drawn structures may be translated within the drawing canvas by selecting an unoccupied area within the drawing canvas and dragging the mouse cursor. The structure(s) will translate as the cursor moves. Similarly, performing the same action but also holding down the shift key will cause rotation of drawn structures.

The Chem Biography database search application manages search, retrieval, and viewing of research data. It functions in one of three primary modes:

Whenever the Chem Biography application is in use, it is always in one of these modes and the user can at any time transfer to an alternate mode via the top level menu commands. Generally, the idea is that one builds a query in input mode, runs a search (transitioning to results mode) to yield a set of compounds (registry ID's) that satisfy the search query. The data to be displayed for those compounds is controlled by the users currently selected view (view mode).

When entering the database search tool from the main menu, the user will be in the input mode and may begin to build queries. A populated search form might appear as shown in Figure 4.1, “Chem Biography Search Input Page”.

A search query is built using one of three mechanisms which may be combined. These mechanisms are described in the sections that follow and defined:

Successful execution of a search will transfer the user to the search results page for analysis of data. An example results page appears below in Figure 4.3, “Chem Biography Search Results Detail”. At this point, the user can modify the display via a series of menu options and then refresh the view. The compound hit list – the output of a search - is always unchanged when displaying search results (with the exception of filtering) but the view may be completely altered to allow the user to analyze the data in a desired manner. This principle, using a search to define a compound hit list but then decoupling the data results view from the input query, is a central tenet of the CB design.

Altering the view is accomplished via menu options and the edit view mode both of which are described in detail below. The menu options also provide the capability to export data to pdf, csv, or text formats.

The available menu options depend on which mode is being used and will be visible at the top of the page.

Transfer to the edit views mode via the edit command adjacent to the views dropdown menu. The edit views mode appears something analogous to what is shown in Figure 4.4, “Edit View Interface” (the exact view is specific to the organizations data types as done in the CB setup). Selecting a view from the view selection menu will automatically check certain checkboxes which correspond to the field names for each of the available data types. The selected checkboxes are the data that will be made visible when a search is run and this view is selected. Edit these as desired and then save to a new name or overwrite and existing view (the general chemical registry, biological data table, and everything views are write protected). The make default button causes the selected view to become the one that is loaded any time a new Chem Biography session is started.

The final CB main page option is for posting of biological data and is designed for data recorded in CSV file format. Selection of this link transfers the user to the upload page as shown in Figure 5.1, “Upload Biological Results”. The user enters the filename of interest and then selects the type of data to be uploaded; options are derived, as for all other functions, from the CB data setup. Selecting the data type will then transfer the user to an intermediate analysis page.

The interim analysis does two principle actions. The first is to check the CSV file headers and compare them to the CB field names recorded for the data type of interest. If there are mismatches the user in notified. In the example shown below in Figure 10, the user had a “row#” column head which was not part of the CB setup. Note that the file can still be uploaded, but the missing column will not be loaded into the database since there is no matching field name (or alias). If this is an important column of interest contact the local administrator of CB to add the field name (or an alias) to the data type setup. This setup is discussed in detail in the final section on administration of CB.

The second action performed during the interim analysis is to verify that registry numbers are consistent with what is found in the database. All uploaded biological data files must have a column referencing the registry ID (or an alias) to allow mapping of the data. This column entry is checked against the registry. In the example shown in Figure 5.2, “Interim Analysis Page for Posting Biological Results”, one registry ID was inadvertently switched. It would be in principle corrected and the file re-uploaded.

Once the user is satisfied that the file is satisfactorily prepared, based on the analysis, the results are posted. Note that this step must be completed to fully upload the data. The user is directed to a summary page that provides a link to the data now uploaded in CB (Figure 5.3, “Indication of Upload Success after post results button click”). Clicking on the link will transfer the user to the search results page where the data can be verified as having been posted.