Optional Parameters

Execute Options

-param: The argument for this flag is the name of a file containing control parameters. The control parameter file acts to either replace or augment the command line interface. All parameters necessary for program execution may be provided in the control parameter file, although any command given explicitly on the command line will supersede options found in the parameter file. The application generates a new parameter file containing the full set of execution parameters upon every execution. The name of the parameter file is created by combining the prefix base name with the ‘.param’ extension.

-mpi_np <n>: Specifies the number of processors n when the application is run in MPI mode.

-mpi_hostfile <filename>: Specifies the name of the file containing processors configuration. For every host this file should contain a line host_name slots=n where n is the number of processors on the host.

Input Options

-mcquery

Combine contiguous conformers in -query file into a multi-conformer query molecule, following the same rules for combining sequential conformers in the -dbase file. By default, this is false and each connection table in the -query file is treated as a separate query. Labelling the conformer by adding a wart to the name can be set using the -qconflabel parameter.

[default = false]

-scdbase

Don’t combine contiguous conformers in -dbase file into a multi-conformer molecule.

Note

For .oeb files that store a multi-conformer molecule directly, this switch has no effect.

[default = false]

General Output Options

-prefix <name>

Prefix used to name output files. Using -prefix FOO will create a hits structure file named like FOO_hits_1.sdf and a report file, FOO_1.rpt, where _1 will be replaced by a sequential number corresponding to the index of the query in the -query file. Additionally, a parameter file containing all options for the current run will be written to FOO.parm. This parameter file can be used with the -param switch.

[default = rocs]

-outputdir <dirname>: Output directory for output files. The directory specified by this parameter must exist otherwise it will be ignored.

-besthits <N>

Search entire dbase file and keep a hitlist, sorted by score given by -rankby switch. Size of hitlist is determined by integer value N. Note that all members of the hitlist must pass the -cutoff, if given, so the final size can be smaller than the N requested. This switch is ignored if -maxhits is given. Note, that if this is set to zero (0) and -maxhits is also zero (0), then no hitlist will be maintained and all results will be streamed directly to the respective output files.

[default = 500]

-cutoff <F>

Cutoff (F) to determine whether a specific overlay should be considered good enough for hitlist inclusion. This is a floating point value and the actual parameter used for the scoring is as defined by the -rankby switch.

[default = -1.0]

-rankby <score>

Score to use for ranking the hitlist. Legal values include:

TanimotoCombo
ShapeTanimoto (tanimoto)
ColorTanimoto
RefTverskyCombo
RefTversky (tverskyq)
RefColorTversky
FitTverskyCombo
FitTversky (tverskyd)
FitColorTversky
Overlap (overlap)

[default = TanimotoCombo]

-maxconfs <N>

Maximum number of overlays returned for each comparison of a dbase molecule with a query molecule. This defaults to 1. As an example, if the query has n conformers and a given dbase molecule has m conformers, then a total of nxm overlays will be performed. By default, the single best one (1) will be returned (if it passes any -cutoff given). Choosing an alternate value for -maxconfs will cause up to the top N of these overlays to be returned and merged into the hitlist. In the hitlist, these conformers will not be associated with each other. Throughout a run, some can drop off the hitlist while others remain.

[default = 1]

-maxhits <N>

Maximum number of hits to return. This option causes ROCS to finish as soon as N molecules are in the hitlist. Useful for a quick check of a query to see what hits it is finding; this option overrides any value for -besthits.

[default = 0]

Hits Output Options

-conflabel

Controls where the conformer index from a database molecule gets labeled on output molecules. The allowed values are none, title, sdtag, and both.

[default = title]

-qconflabel

Controls whether the conformer index from a query molecule gets labeled on output molecules. The allowed values are none and title.

[default = title]

-outputquery

Put the query structures at the top of the output structure file. This is very useful for keeping the query structure in the same file as the hits, so that for instance, you only need to load one file into VIDA to browse the results. For a grid query, a copy of the grid will be written to PREFIX_ref.grd, where PREFIX is defined by the -prefix commandline option.

[default = true]

-nostructs

Don’t write a structure file. There are times when all you really want are the numerical results from ROCS. If you don’t want or need an output structure file, you can prevent its creation with this switch.

[default = false]

-hitsfile <filename>

Instead of writing to PREFIX_hits_n.sdf (for example) where PREFIX is provided by the -prefix commandline flag, write all hit structures to the file provided with this flag. Can be a filename or full/relative path. Also, if the name provided is actually a molecule file format extension (i.e. .sdf, .mol2.gz, .oeb, etc.), ROCS will write to stdout using the format derived from the file extension. For example if the following is used:

-hitsfile .sdf

then ROCS will write all the hits out to stdout in SDF format.

Note that this option will only work for a single query. If more than one query is provided along with the -hitsfile option, ROCS will issue an error and stop.

-oformat <extension>

Format for the output structure file(s). This option gives a file extension to be used for all output structure files. The format for the file is determined from the extension. Valid values include all the molecule file formats listed in the table above for -query files.

[default = oeb.gz]

-sdTags: This parameter controls whether to attach score information to output molecules as SD data.

Report Output Options

-reportfile <filename>: Instead of writing to PREFIX_n.rpt where PREFIX is provided by the -prefix commandline flag, write all report information (stats) to the file provided with this flag. Can be filename or full/relative path. Note that if more than one query molecule is provided, this flag will not work unless the -report flag is also set to one to put all report info into one report file.

-report

Controls report file generation. The default, each, writes a separate report file for each query in the -query file. If one is chosen, stats for multiple queries in the same -query file will be placed in a single report file. This is useful for computing a NxN comparison of a file as both the dbase and query. Finally, to prevent ROCS from writing report files, use none.

[default = each]

-stats

Determines which stats get placed into report files. Values include hits (the default), best and all. The default is to include just the stats for the compounds in the hitlist. If best is chosen, the report file will include stats for the best overlay(s) for every dbase molecule. The number of best overlay score is determined by the value of -maxconfs. Finally, if all is given, stats for every single overlay will be placed in the report file. Be careful. For a multi-conformer query against a large dbase file, all can generate a HUGE amount of data.

[default = hits]

Status Output Options

-statusfile <filename>: Instead of writing to PREFIX_n.status where PREFIX is provided by the -prefix commandline flag, write all status information to the file provided with this flag. Can be filename or full/relative path. Note that if more than one query molecule is provided, the status written to this file is only for the most recently processed query.

-status

Controls status file generation. The default, each, writes a separate status file for each query in the -query file. If one is chosen, the status for multiple queries in the same -query file will be placed in a single status file. Note that if more than one query molecule is provided, the status written to this file is only for the most recently processed query. Finally, to prevent ROCS from writing status files, use none.

[default = each]

Log Output Options

-logfile <filename>: Filename for log file. Overrides log filename created from -prefix.

-progress <method>

Method for showing job progress on the command line. Choices include:

percent - show a percent complete progress bar (DEFAULT)
log - echo the log message for each molecule
dots - show dots
none - print nothing to console

-verbose: Add extra verbosity to log file.

Shape Options

-tanimoto_cutoff <F>

Flag that can be used to limit output hits to only those with some minimum shape score. This can be used regardless of which score is chosen (-rankby) for ranking the hitlist. For example, using:

-rankby TanimotoCombo -cutoff 1.1 -tanimoto_cutoff 0.6

any molecule with Shape Tanimoto <= 0.6 will not be retained. Additionally, the constraint on TanimotoCombo to be at least 1.1 implies that Color Tanimoto must also be > 0.5 so that the sum can be greater than 1.1.

[default: 0.0]

-randomstarts <N>: Specifies number (N) of random starting positions to try instead of inertial frame overlay as described in the theory section. Since inertial frame alignment involves 4 (or 8 in the case of highly symmetric molecules) starting positions, setting -randomstarts to a value much larger will result in much slower run times.

-subtan: Also calculate sub-Tanimoto score. See the Report File section for a complete description of how sub-Tanimoto is calculated.

-subrocs: Specifies starting the search at all heavy atoms of the larger molecule as well as the default inertial starts. The larger molecule is chosen by comparing the self shape-overlap terms of the query and database molecule. The -subrocs option is especially useful when the query and database molecules have a large difference in size.

-shapeonly

A color force field is used by default and optimization against shape and color is the default overlap method. It is incompatible with a shape file. As an easy way to run ROCS with just shape overlap, this flag is the equivalent of setting:

-chemff none
-optchem false
-rankby tanimoto

-scoreonly

Perform scoring calculation only on input molecules. Sets the following flags:

-opt false
-optchem false
-besthits 0
-maxhits 0
-scdbase

-opt

Turn optimizer on if true, off if false. Not normally used by itself, but with other flags via the -scoreonly flag.

[default = true]

Color Options

-chemff <cffname>

Color-force-field name. Either the name of one of the built-in color force fields (ImplicitMillsDean or ExplicitMillsDean) or the name of a user-defined color force field file. The format of this file is given in the Color Force Field section.

[default = ImplicitMillsDean]

-optchem

Use color force field forces and gradients as part of overlay optimization. Ignored when -opt is false.

[default = true]

-coloronly

Enables overlay optimization against only the color components, i.e., color atoms for a molecule or color gaussians for a shape query, of the query. This provides a color equivalent option of the corresponding -shapeonly option.

[default = false]