Problems, Workarounds, Clarifications (FAQ)

1. When attempting to Create a HintMap or HintTable, HINT tells you to partition the molecule first even though you already have. This message is generated by the SPL code of HINT as it attempts to verify that the contents of the molecular area you wish to map, etc. are the same as when you last partitioned that molecular area and created a partition results scratch file. Basically the SPL code compares the molecule names (current molecule in Mx and that in HINT Mx scratch file) as string variables. If the names are particularly complex, with spaces, parentheses or other special characters, the SPL string comparison function can, and often does, fail to recognize two apparently identical strings as being the same. If you get this error, the simplest workaround is to change the name of the molecule within SYBYL to a simpler one. A new information dialog, to remind you of this workaround, will appear immediately after the "You must first partiton..." error dialog.

2. Spreadsheet functions fail with cryptic messages implying shell errors. This can sometimes happen if the name of your molecule has spaces or quotes single or double) imbedded. What is happening is that when the HINT SPL program attempts to pass the molecule information to the HINT executable the unix shell interpreter can not parse the information properly. The workaround is to change the name of the molecules in the database.

3. A lot of other serious HINT problems arise from path, environment, and protection difficulties and inconsistencies. Each time the actual HINT executable is run from within SYBYL, it is a new shell being spawned, with the user's own .cshrc, etc. being executed. If HINT is not defined in the .cshrc, e.g., if the user defines HINT by sourcing its definition file directly, then the important HINT environmental variables may not be properly defined and HINT will not function as designed. Often the "ridiculously long path" unix error accompanies this problem. Another related potential source of this type of problem arises when the HINT scratch files, written to the user's ~/dumpster directory, don't have write privilege. (This may occur, for example, if root privilege was earlier used to run HINT.) HINT attempts to reuse the same filenames to reduce disk space, and if HINT can't write to one of its scratch files, it will fail.

4. Most HINT errors are currently reported only in the SYBYL text window. Thus the SPL part of the program does not know that the HINT executable had a problem, and may report results in dialog boxes that are artifacts from previous HINT sessions. We will continue to supplement the HINT error reporting with upcoming releases, but there is a significant tradeoff here. The more error checking that is done with the SPL code (and all screen dialogs are generated by SPL), the slower and more unresponsive the HINT user interface becomes. The obvious workaround is to monitor the SYBYL text window for error messages from the HINT executable.

5. The message: Warning: Adjacent "Fragments" involving Atoms... FPP(0) used to estimate Log P appears when partitioning. This message is simply a warning from the Partition algorithm that your molecule has a functional group or Leo-type fragment that is not in the database. HINT continues the calculation by constructing a new fragment from two (or more) fragments that are present in the database with the application of a polar proximity factor of range zero, FPP(0). FPP(0) represents the polar proximity effect of two groups that have no "insulating carbons" between them. Of course this means that the estimation of LogP that HINT produces is not as valid as one obtained with all of the necessary fragments present in the database, but it is a pragmatic solution to missing data.

6. There have been some comments on the difficulty of getting all of the atom types correctly set for small molecule (i.e., calculate method) partition calculations. This is a major bore, but it is of utmost importance to get the best partitioning results. We would like to point out that there are few other properties as sensitive to small changes in structure as the LogP. For example, adding one methyl to a molecule adds 0.8-0.9 log units to its hydrophobicity, or in other words changes its solubility by nearly an order of magnitude!

7. SYBYL issues a steady stream of comments about files failing to open in R mode. Most of these arise because in the HINT SPL code we chose to ask the user to verify if he wants to write over an existing file of the same name. The only way to do this is to first check to see if the file already exists by trying to open it with R(ead) mode, which is the source of the "errors" reported by SYBYL.

8. When using the HintCoMFA command, SYBYL fills the HINTCOMFA column with zeroes and also asks you to check field values for each row in the table. Both of these are perfectly normal. SYBYL always tells you to check field values when an externally generated field is imported into the spreadsheet. The 0.00 value placed in the spreadsheet for the HINTCOMFA column only represents a placeholder for purposes of display, the actual column contains all of the field values for the entire grid. The value visible in the column probably represents the first grid value (one of the corners of the grid cage) which is almost always zero.

9. Some parts of HINT, especially having to do with the Spreadsheet, may not work with X-terminal emulators on PCs and Macintoshes and occasionally on SGIs. Sometimes, and it does not seem to be particularly reproducible, the HINTCOMFA item is missing from the Molecular Spreadsheet Autofill menu. If this happens type "mss!reset_eslc" to the Sybyl> prompt before hitting Autofill. This simple command appears to clear up this problem by re-defining a few of the HINT-specific macros that may have been overwritten by SYBYL.

10. Some statistical functions operating on Field columns in the MSS give irreproducible results when there is HINT field present. This may be related to the problem described next. There apparently is a memory instability in Sybyl associated with externally generated fields. The workaround is to save the table (MSS) and exit Sybyl after filling the field columns and then re-start Sybyl and resume.

11. When you try and "customize" a HINT field in CoMFA for some comparative studies, you get the same result as you get with the original HINT field. This is caused by a long-standing SYBYL bug that apparently prohibits you from filling more than one CoMFA-type column from an externally-generated field per SYBYL session. The Workaround, which is less than satisfying, is to save your Spreadsheet, exit and restart SYBYL for each HINT column you wish to add to your spreadsheet.

12. It is difficult to graph the results of a PLS study that involves a HINT field. As Tripos "improved" their dialog boxes for using the spreadsheet and CoMFA, they made it more difficult to graph fields other than the standard steric and electrostatic ones The View CoMFA dialog under QSAR has no provisions for looking at anything other than the standard two field types (it is quite nice for that, though). The Graph HintQSAR dialog under HintQSAR should help here.

13. You cannot "Pick" points on QSAR graphs from PLS studies that include a HINT field. Again this appears to be a bug in SYBYL. The "problem" graph is "ORIGINAL_DATA" -- if that one is active, the SYBYL Pick function always chooses the first row of the Table, regardless of your actual selection. The workaround is to go into the QSAR, Manage QSAR, Select Graphs... dialog and choose COEFFICIENTS, PREDICTED_ACTUAL and/or QQ_PLOT as the graphs to be plotted. Selection of ORIGINAL_DATA or ALL (which includes ORIGINAL_DATA) seems to activate the SYBYL bug.

14. You cannot Predict Properties from PLS Models that include the HINT Field. This is apparently an error in the graphical MSS interface: From the molecular spreadsheet the menubar command
    
    QSAR >> Predict Property ...
    
    does not work correctly if external fields like a HINT field are used in the CoMFA/PLS calculation! To check: simply predict the activities of the training set. They are different from the fitted predictions of the PLS analysis.
    Workaround: Use the command mode command in the text window:
    
    QSAR >> Analysis >> Predict >> Row expression(*)
    
    The simplest way to perform an external prediction is to include the compounds to be predicted into the molecular spreadsheet, to omit them from the CoMFA analysis, and finally use this command for prediction. (This error and workaround was prepared by Michael Wiese of Martin Luther Universität.)

HINT 3.06S Installation Instructions

HINT is released as a UNIX tar set in a variety of tape formats. The release consists of an executable image "hint", executable images for several small utility programs, and extensive SPL (SYBYL Programming Language) script that creates menus, dialog boxes, and macros to execute the HINT programs. The installation (cshell) script places the HINT files in appropriate subdirectories under a new eduSoft directory tree and makes a few very minor (and easily reversible) changes to the SYBYL directory tree. A new cshrc file is created that, when "sourced", causes SYBYL to come up with HINT installed in its menu system. The HINT installation creates a parallel directory structure which in no way affects the performance and integrity of the previously installed Tripos tree.

The HINT 3.06S installation consists of three components: 1) installing the HINT software, 2) making a few minor changes to the Sybyl environment to enable HINT, and 3) setting up user accounts to give them access to HINT. Although it is not strictly necessary, the installation of HINT 3.06S is best performed as the "superuser" Special cases for: 1) Installing HINT "on top of" Molconn-Z, 2) Installing HINT and Molconn-Z together, and 3) Installing the stand-alone (non-interfaced) HINTLOGP 3.06 are described below.

1. Make a root directory for the eduSoft products. We recommend /usr/eduSoft, but any location will work. The unix command for this step is: mkdir /usr/eduSoft

2. Unload the HINT 3.06S tape (or FTP tar-set) into this directory:
   • cd /usr/eduSoft
   • tar xov (tar xovf hint306s)

3. Make sure Sybyl is defined. If you are not sure, check to see if the environment variable TA_ROOT is defined:
   • echo $TA_ROOT
   If $TA_ROOT is not defined, you will have to perform the steps you usually undertake to run Sybyl up to the point where you enter sybyl to the unix prompt.

4. The HINT installation makes the following changes to the Sybyl environment. Verify that there are not local modifications to these files that will be lost when HINT is installed.
   • The NetBatch application list, $TA_ROOT/batch/admin/APPLICATION, is modified to include the new HINT applications so that they can be run through Sybyl NetBatch. Note that if you have local additions to the APPLICATION list, you should manually add the new HINT applications.
   • The HINT NetBatch shell programs are copied into the appropriate Sybyl directory $TA_ROOT/batch/cmd.
   • Two files are copied into the $TA_ROOT/sybylbase/tables/ta_coltypes directory to define the HINTLogP and HINTScore column types. (This directory has been created by Tripos for this purpose.)

5. Execute the HINT 3.06S installation script (if you are comfortable with the changes to the Sybyl environment described). The installation script is quite simple, and the functions it includes can be performed manually if you wish to intercept any of the steps.
   • cd eslc
   • sh install_hint306s

6. Edit $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh to add the following features: a) define two Tripos variables, TA_MENUBAR_USER_INIT and TA_MSS_USER_INIT, as null; b) define the EDUSOFT_ROOT environmental variable; c) "source" a platform-and product-specific definitions file that defines the a variety of eduSoft environment variables; and d) activate user specific startup information for Sybyl (the .sybylrc file, see below).

   To do this:

   1. append install/ta_site.csh_eslc to $TA_ROOT/lib/ta_site.csh either with the editor or the unix cat command.
   2. append install/ta_site.sh_eslc to $TA_ROOT/lib/ta_site.sh either with the editor or the unix cat command.
   3. edit both $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh so that the proper location of $EDUSOFT_ROOT is set (assumed above to be /usr/eduSoft) and that the proper cshrc and profile files are defined for the SGI processor you are using and the eduSoft products you are installing (see the table below). (All other HINT environment variables are defined relative to $EDUSOFT_ROOT.) If you are on a mixed network of processors, you may have to add some shell logic here to call the correct definition files.
   4. also in $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh make sure that the TA_USER_STRT option is turned on and pointing to $HOME/.sybylrc.

      Product(s)	cshrc (in ta_site.csh)	profile (in ta_site.sh)
      Hint 3.06S	cshrc_hint	profile_hint
      Hint 3.06S & MolconnZ 4.03S	cshrc_hint+mconn	profile_hint+mconn
      Hint 3.06S & HASL 4.00S	cshrc_hasl+hint	profile_hasl+hint
      Hint 3.06S, MolconnZ 4.03S & HASL 4.00S	cshrc_hasl+hint+mconn	profile_hasl+hint+mconn

   5. Install the HINT License Keys(s) as described on the included (hardcopy) documentation or on-line.

   6. Enable HINT 3.06S for users. All users who want to use the HINT program through Sybyl must modify (or create) their individual .sybylrc files to include the two lines in the file $EDUSOFT_ROOT/eslc/install/sybylrc. These added lines are two commands that Sybyl must execute on startup in order for HINT to be defined.
      • vi ~user/.sybylrc
      • make appropriate changes (for each user)...
      Note that HINT 3.06S uses each user's dumpster directory as a scratch location for temporary files. Confirm that each HINT user has a ~user/dumpster.

   7. Try it out. Re-login or re-source the .cshrc file and run Sybyl. If HINT 3.06S is set up properly, the messages "Loading eslc menubar descriptions" and "Loading Hint macro definitions and dialogs" will appear in the graphics screens after the usual Sybyl messages. There should be a new pulldown "eslc" on the Sybyl menubar which includes a "Hint" menu item. Follow all of the HINT Tutorials in the manual for a complete introduction to the program, but it is advisable at this point to try at least a portion of Lesson 1 to confirm that the license is properly configured and that the program is operational.

   Adding HINT to a Site that has Molconn-Z and/or HASL

   1. Unload the HINT 3.06S tape (or FTP tar set) into the current $EDUSOFT_ROOT directory:
      • cd $EDUSOFT_ROOT
      • tar xov (tar xovf hint306s)

   2. Execute the HINT 3.06S installation script (if you are comfortable with the changes to the Sybyl environment described in detail in Step 4 above). The installation script is quite simple, and the functions it includes can be performed manually if you wish to intercept any of the steps.
      • cd eslc
      • sh install_hint306s_after_mconn310s

   3. Edit both $TA_ROOT/lib/ta_site.csh and $TA_ROOT/lib/ta_site.sh so that the proper location of $EDUSOFT_ROOT is set (assumed above to be /usr/eduSoft) and that the proper cshrc and profile files are defined for the SGI processor you are using and the eduSoft products you are installing (see the table above). (All other HINT environment variables are defined relative to $EDUSOFT_ROOT. If you are on a mixed network of processors, you may have to add some shell logic here to call the correct definition files.

   4. Steps 7, 8 and 9 above.

   Installing HINT and Molconn-Z Together

   1. Make a new directory for the eduSoft products, e.g., mkdir /usr/eduSoft.

   2. Unload the HINT 3.06S tape (or FTP tar set) and Molconn-Z 3.50S tape (or FTP tar set) into this directory:
      • cd /usr/eduSoft
      • tar xov (tar xovf hint306s)
      • tar xov (tar xovf mconn350s)

   3. Execute the installation script (if you are comfortable with the changes to the Sybyl environment described in detail in Step 4 above). The installation script is quite simple, and the functions it includes can be performed manually if you wish to intercept any of the steps.
      • cd eslc
      • sh install_hint306s_and_mconn403s

   4. Step 6 above.

   5. Install the HINT and Molconn-Z License Keys(s) as described on the included (hardcopy) documentation or on-line.

   6. Steps 8 and 9 above.

   Installing (and Running) the Standalone HINTLOGP (3.06)

   This version of HINT is designed to calculate LogP from SMILES strings in the Daylight .smi file format or from command line input. The program is intended to be very fast, for processing large quantitites of data, so has few options. This version of HINT reads and decodes SMILES files using the Daylight Toolkit. This is an optional feature that requires additional licensing from eduSoft, LC and a run-time SMILES Toolkit license from Daylight Chemical Information Systems, Inc. Each record of the Daylight SMILES files, which are generally named with the .smi extension, is simply a SMILES String followed by the Molecule Name (space delimited). There is no file termination code.
   1. Unload the HINTLOGP 3.06 tape (or FTP tar set) into the current $EDUSOFT_ROOT directory:
      • cd $EDUSOFT_ROOT
      • tar xov (tar xovf hintlogp306)

   2. Choose the appropriate HINTLOGP login file(s) (see table below). Edit that/those files in /usr/eduSoft/eslc/lib/ to correct the environment for $EDUSOFT_ROOT. If you have a network license and a mixed-platform network, you may have to create some logic to automatically select the appropriate cshrc.

      Product(s)	Platform	cshrc	profile
      HintLogP 3.06	cshrc_hintlogp	profile_hintlogp
      HintLogP 3.06 & Molconn-Z 4.05	cshrc_hintlogp+molconnz	profile_hintlogp+molconnz

   3. In order to activate HINT, one of these files must be manually "sourced" with e.g., source /usr/eduSoft/eslc/lib/cshrc_??? which can be placed in the system or each users .cshrc file.

   4. Install the HINT License Keys(s) as described on the included (hardcopy) documentation or on-line.

   5. Copy your Daylight License Key into /usr/eduSoft/eslc/license/DayLicense.dat or redirect the pointers to DY_LICENSEDATA in the appropriate cshrc_??? or profile_??? file(s).

   6. To run this version of HINT, use the following syntax to the unix command line:

      $HINT_RUN/hint n smilessource m

      where:

      n is either 0 or 1; if n is 0 then the smilessource is a SMILES string (in quotes); if n is 1 then the smilessource is a .smi SMILES file.

      smilessource is either an explicit SMILES string or a valid file name in .smi format.

      m is either 0 or 1; if m is 0 then the short output format will be provided; if m is 1 the more verbose output is written.

   Special Notes for "Customized" Sybyl Sites

   There can be difficulties with the above procedures if there have already been local modifications made to your Sybyl installation. For example, if the $TA_MENUBAR_USER_INIT or $TA_MSS_USER_INIT variables are already being used at your site to define new functions, the described installation procedure should be modified. To make it easy to merge the HINT/Molconn-Z SPL files wth other applications, there are two types of environmental variables in the HINT/Molconn-Z setup. The first, $ESLC_SPL, points to files (which are named with the eslc_ prefix) that may be moved to another directory or otherwise modified to fit the local requirements. The other type of environmental variable is specific to the product, i.e., $HINT_SPL and $MCONN_SPL; these are reserved for files that are specific to the product (i.e., HINT and Molconn-Z) functionality. The root of the HINT and Molconn-Z additions to Sybyl are in the files: $ESLC_SPL/eslc_sybyl.spl and $ESLC_SPL/eslc_spreadsheet.spl, which are pointed to by $TA_MENUBAR_USER_INIT and $TA_MSS_USER_INIT, respectively.

   If there are questions or difficulties with the HINT/Molconn-Z installation, please feel free to give us a call.