.. include:: substitutions
.. include:: ../apps-substitutions

.. _chapter_hlmerge:

***********
HLMerge
***********

=========
Overview
=========

This utility takes as input a single molecule file (SD or OEB) or list file containing one or more molecules files. It
will re-rank these input files by a user-defined SD tag. The most common use is to create a single hitlist after running
**ROCS** on the separate files created by chunker.

======================
Example Commands 
======================

Assuming a set of ROCS results for the previous chunker example are in a file called ``bar.list``:

.. code-block:: bash

    bar0000001_hits_01.sdf
    bar0000002_hits_01.sdf
    bar0000003_hits_01.sdf
    bar0000004_hits_01.sdf
    bar0000005_hits_01.sdf

To merge these, rank by Tanimoto Combo and then keep the top 200.

.. code-block:: bash
    
    prompt> hlmerge -in bar.list -out bar_hits.sdf -rankby ROCS_TanimotoCombo -besthits 200

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **HLMerge**
with the `--help` option.

.. code-block:: console
   
   > hlmerge --help

will generate the following output:

::

   Help functions:
     hlmerge --help simple      : Get a list of simple parameters
     hlmerge --help all         : Get a complete list of parameters
     hlmerge --help defaults    : List the defaults for all parameters
     hlmerge --help <parameter> : Get detailed help on a parameter
     hlmerge --help html        : Create an html help file for this program
     hlmerge --help versions    : List the toolkits and versions used in the application

======================
Required Parameters 
======================

.. option::  -in <filename>


   Name of input file to rank, or the name of a list file
   (:file:`.lst` or :file:`.list`) containing a collection of files to rank.
   [Aliases=**-i**]

   
..  option::  -out <filename>


    Output structure file for sorted hits. Formats other than SDF or OEB will lose the SD tag data.
    [Aliases=**-o**]

    
..  option::  -rankby <SD tag>

    SD tag containing a score (that can be converted to a floating point value) to use as the score to rank with.
	
======================
Optional Parameters 
======================

.. option:: -besthits N

    Number of hits to keep.
    [Default=500]

.. option:: -biggerisbetter

    By default, hits are ranked with higher scores meaning better results. To rank by a score 
    where the smaller value is better, use -biggerisbetter false.
    [Default=true]
