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

.. _filter_examples:

.. program:: filter

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

.. note::

   ``filter`` may need to be replaced by ``filter.bat`` on Windows PowerShell.

This section includes several sample **FILTER** command line executions.  Each
example is followed by a brief description of its behavior.

.. code-block:: bash

   prompt> filter drugs.smi drugs.oeb.gz
   prompt> filter -in drugs.smi -out drugs.oeb.gz

These two commands will yield identical results.  These execute **FILTER** with the
default parameters.  The file `drugs.smi` is opened in SMILES format for
input, and the output is written to the file `drugs.oeb.gz` in gzipped
OEBinary version 2 format.

.. code-block:: bash

   prompt> filter -in drugs.smi -out drugs.sdf -filter myfilter


This command is the same as the one above except for the `-filter` flag.
It executes **FILTER** with the parameters found in the `myfilter` file.
The file `drugs.smi` is opened in SMILES format for input, and the output
is written to the file `drugs.sdf`.

.. code-block:: bash

   prompt> filter -param myparameters drugs.smi drugs.oeb.gz
   prompt> filter drugs.smi drugs.oeb.gz -param myparameters


The first of these two commands will yield exactly the same results as the
example above.  The file `drugs.smi` will be mapped to the `-in` flag and
`drugs.oeb.gz` will be mapped to the `-out` flag, being the second to
last and last command line arguments, respectively.  Unfortunately, the second
of these two commands will fail to parse because the implicit input and output
arguments are not the final two arguments in the list.

.. code-block:: bash

   prompt> filter -in drugs.smi -out drugs.oeb.gz -table drugs.table


This executes **FILTER** on the file `drugs.smi` and writes molecules that
pass the filter to the file `drugs.oeb.gz`.  It also writes all of the filter data to the tab-separated value file `drugs.table`.

.. code-block:: bash

   prompt> cat maybridge.05-1.sdf |filter -in .sdf -out .ism|oeomega classic .ism m.oeb.gz


This command presumes that you have an SD format file called
`maybridge.05-1.sdf`.  That file is piped to the **FILTER** program.
The `-in .sdf` flag indicates that **FILTER** should read .sdf format from
std::in.  Since no `-filter` flag is specified, the default filter will be
used.  The `-out .ism` flag indicates **FILTER** will write isomeric smiles
format to std::out.  The output would then be piped into **OMEGA**.

.. code-block:: bash

   prompt> filter -in drugs.smi -out drugs.oeb.gz -select "[N;$(*-a)]"


This command will filter the compounds in `drugs.smi` with the default filter
and write the output to `drugs.oeb.gz`.  It
also requires that molecules contain exactly one instance of the aniline
substructure defined by the SMARTS pattern `"[N;$(*-a)]"`.

.. note::

   ``filter.bat -in drugs.smi -out drugs.oeb.gz "-select [N;\`$(*-a)]"`` must be used
   instead on Windows PowerShell.

