.. _summary:

Summary
=======

These tables summarize BEDOPS utilities by option, file inputs and BED column requirements.

=======================================
Set operation and statistical utilities
=======================================

--------------
``bedextract``
--------------

* Efficiently extracts features from BED input.
* BEDOPS :ref:`bedextract` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| ``--list-chr``                | Print every chromosome found in ``input.bed``                        | 1                | 1                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``<chromosome>``              | Retrieve all rows for specified chromosome, *e.g.* ``bedextract chr8 | 1                | 1                | 3                |
|                               | input.bed``                                                          |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``<query> <reference>``       | Grab elements of ``query`` that overlap elements in reference. Same  | 2                | 2                | 3                |
|                               | as ``bedops -e -1 query reference``, except that this option fails   |                  |                  |                  |
|                               | when ``query`` contains fully-nested BED elements. May use ``-`` to  |                  |                  |                  |
|                               | indicate ``stdin`` for ``reference`` only.                           |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

----------
``bedmap``
----------

* Maps source signals from ``map-file`` onto qualified target regions from ``ref-file``. Calculates an output for every ``ref-file`` element.
* BEDOPS :ref:`bedmap` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| ``--bases``                   | Reports the total number of bases from ``map-file`` that overlap the | 1                | 2                | 3                |
|                               | ``ref-file`` 's element.                                             |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bases-uniq``              | Reports the number of distinct bases from ``ref-file`` 's element    | 1                | 2                | 3                |
|                               | overlapped by elements in ``map-file``.                              |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bases-uniq-f``            | Reports the fraction of distinct bases from ``ref-file`` 's element  | 1                | 2                | 3                |
|                               | elements in ``map-file``.                                            |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bp-ovr <int>``            | Require ``<int>`` bases of overlap between elements of input files.  | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--chrom <chromosome>``      | Process data for given ``<chromosome>`` only.                        | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--count``                   | Reports the number of overlapping elements in ``map-file``.          | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--cv``                      | Reports the Coefficient of Variation: the result of ``--stdev``      | 1                | 2                | 5                | 
|                               | divided by the result of ``--mean``.                                 |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--ec``                      | Error-check all input files (slower).                                | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--echo``                    | Echo each line from ``ref-file``.                                    | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--echo-map``                | Reports the overlapping elements found in ``map-file``.              | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--echo-map-id``             | Reports the IDs (4th column) from overlapping ``map-file`` elements. | 1                | 2                | 4                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--echo-map-id-uniq``        | List unique IDs from overlapping ``map-file`` elements.              | 1                | 2                | 4                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--echo-map-range``          | Reports the genomic range of overlapping elements from ``map-file``. | 1                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--echo-map-score``          | Reports the scores (5th column) from overlapping ``map-file``        | 1                | 2                | 5                |
|                               | elements.                                                            |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--faster``                  | **(Advanced)** Strong input assumptions are made. Review documents   | 1                | 2                | 5                |
|                               | before use. Compatible with ``--bp-ovr`` and ``--range`` overlap     |                  |                  |                  |
|                               | options only.                                                        |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--fraction-ref <val>``      | The fraction of the element's size from ``ref-file`` that must       | 1                | 2                | 5                |
|                               | overlap the element in ``map-file``. Expects ``0 < val <= 1``.       |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--fraction-map <val>``      | The fraction of the element's size from ``map-file`` that must       | 1                | 2                | 5                |
|                               | overlap the element in ``ref-file``. Expects ``0 < val <= 1``.       |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--fraction-both <val>``     | Both ``--fraction-ref <val>`` and ``--fraction-map <val>`` must be   | 1                | 2                | 5                |
|                               | true to qualify as overlapping. Expects ``0 < val <= 1``.            |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--fraction-either <val>``   | Both ``--fraction-ref <val>`` and ``--fraction-map <val>`` must be   | 1                | 2                | 5                |
|                               | true to qualify as overlapping. Expects ``0 < val <= 1``.            |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--exact``                   | Shorthand for ``--fraction-both 1``. First three fields from         | 1                | 2                | 5                |
|                               | ``map-file`` must be identical to ``ref-file`` element.              |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--indicator``               | Reports the presence of one or more overlapping elements in          | 1                | 2                | 3                |
|                               | ``map-file`` as a binary value (``0`` or ``1``).                     |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--kth <val>``               | Reports the value at the *k* th fraction. A generalized median-like  | 1                | 2                | 5                |
|                               | calculation, where ``--kth 0.5`` is the median. (``0 < val <= 1``)   |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--mad <mult=1>``            | Reports the 'median absolute deviation' of overlapping elements in   | 1                | 2                | 5                |
|                               | ``map-file``, multiplied by ``<mult>``.                              |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--max``                     | Reports the highest score from overlapping elements in ``map-file``. | 1                | 2                | 5                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--max-element``             | An element with the highest score from overlapping elements in       | 1                | 2                | 5                |
|                               | ``map-file``. If no overlapping element exists, ``NAN`` is reported. |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--mean``                    | Reports the average score from overlapping elements in ``map-file``. | 1                | 2                | 5                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--median``                  | Reports the median score from overlapping elements in ``map-file``.  | 1                | 2                | 5                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--min``                     | Reports the lowest score from overlapping elements in ``map-file``.  | 1                | 2                | 5                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--min-element``             | An element with the lowest score from overlapping elements in        | 1                | 2                | 5                |
|                               | ``map-file``. If no overlapping element exists, ``NAN`` is reported. |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--stdev``                   | Reports the square root of the result of ``--variance``.             | 1                | 2                | 5                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--sum``                     | Reports the accumulated value from scores of overlapping elements in | 1                | 2                | 5                |
|                               | ``map-file``.                                                        |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--tmean <low> <hi>``        | Reports the mean score from overlapping elements in ``map-file``,    | 1                | 2                | 5                |
|                               | after ignoring the bottom ``<low>`` and top ``<hi>`` fractions of    |                  |                  |                  |
|                               | those scores. (``0 <= low <= 1``, ``0 <= hi <= 1``, ``low + hi <=    |                  |                  |                  |
|                               | 1``).                                                                |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--variance``                | Reports the variance of scores from overlapping elements in          | 1                | 2                | 5                |
|                               | ``map-file``.                                                        |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

----------
``bedops``
----------

* Offers set and multiset operations for files in BED format.
* BEDOPS :ref:`bedops` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| ``--chrom <chromosome>``      | Process data for given ``chromosome`` only.                          | 1                | No imposed limit | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--complement``, ``-c``      | Reports the intervening intervals between the input coordinate       | 1                | No imposed limit | 3                |
|                               | segments.                                                            |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--difference``, ``-d``      | Reports the intervals found in the first file that are not present   | 2                | No imposed limit | 3                |
|                               | in any other input file.                                             |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--ec``                      | Error-check input files (slower).                                    | 1                | No imposed limit | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--element-of``, ``-e``      | Reports rows from the first file that overlap, by a specified        | 2                | No imposed limit | 3                |
|                               | percentage or number of base pairs, the merged segments from all     |                  |                  |                  |
|                               | other input files.                                                   |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--header``                  | Accept headers (VCF, GFF, SAM, BED, WIG) in any input file.          | 1                | No imposed limit | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--intersect``, ``-i``       | Reports the intervals common to all input files.                     | 2                | No imposed limit | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--merge``, ``-m``           | Reports intervals from all input files, after merging overlapping    | 1                | No imposed limit | 3                |
|                               | and adjoining segments.                                              |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--not-element-of``, ``-n``  | Reports exactly everything that ``--element-of`` does not, given the | 2                | No imposed limit | 3                |
|                               | same overlap criterion.                                              |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--partition``, ``-p``       | Reports all disjoint intervals from all input files. Overlapping     | 1                | No imposed limit | 3                |
|                               | segments are cut up into pieces at all segment boundaries.           |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--range L:R``               | Add ``L`` bases to all start coordinates and ``R`` base to end       | 1                | No imposed limit | 3                |
|                               | coordinates. Either value may be positive or negative to grow or     |                  |                  |                  |
|                               | shrink regions, respectively. With the ``-e`` or ``-n`` operation,   |                  |                  |                  |
|                               | the first (reference) file is not padded, unlike all other files.    |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--range S``                 | Pad input file(s) coordinates symmetrically by ``S`` bases. This is  | 1                | No imposed limit | 3                |
|                               | shorthand for ``--range -S:S``.                                      |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--symmdiff``, ``-s``        | Reports the intervals found in exactly one input file.               | 2                | No imposed limit | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--everything``, ``-u``      | Reports the intervals from all input files in sorted order.          | 1                | No imposed limit | 3                |
|                               | Duplicates are retained in the output.                               |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

--------------------
``closest-features``
--------------------

* For every element in ``input-file``, find those elements in ``query-file`` nearest to its left and right edges.
* BEDOPS :ref:`closest-features` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| (no option)                   | NA                                                                   | 2                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--chrom <chromosome>``      | Process data for given ``<chromosome>`` only.                        | 2                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--dist``                    | Output includes the signed distances between the ``input-file``      | 2                | 2                | 3                |
|                               | element and the closest elements in ``query-file``.                  |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--ec``                      | Error-check all input files (slower).                                | 2                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--no-overlaps``             | Do not consider elements that overlap. Overlapping elements,         | 2                | 2                | 3                |
|                               | otherwise, have highest precedence.                                  |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--no-ref``                  | Do not echo elements from ``input-file``.                            | 2                | 2                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--closest``                 | Choose the nearest element from ``query-file`` only. Ties go to the  | 2                | 2                | 3                |
|                               | leftmost closest element.                                            |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

=======
Sorting
=======

------------
``sort-bed``
------------

* Sorts input BED file(s) into the order required by other utilities. Loads all input data into memory.
* BEDOPS :ref:`sort-bed` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| (no option)                   | NA                                                                   | 1                | 1000             | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--max-mem <val>``           | ``<val>`` specifies the maximum memory usage for the :ref:`sort-bed` | 1                | 1000             | 3                |
|                               | process, which is useful for very large BED inputs. For example,     |                  |                  |                  |
|                               | ``--max-mem`` may be ``8G``, ``8000M``, or ``8000000000`` to specify |                  |                  |                  |
|                               | 8 GB of memory.                                                      |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

==========================
Compression and extraction
==========================

----------
``starch``
----------

* Lossless compression of any BED file.
* BEDOPS :ref:`starch` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| (no option)                   | NA                                                                   | 1                | 1                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bzip2`` or ``--gzip``     | The internal compression method. The default ``--bzip2`` method      | 1                | 1                | 3                |
|                               | favors storage efficiency, while ``--gzip`` favors compression and   |                  |                  |                  |
|                               | extraction time performance.                                         |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--note="foo bar..."``       | Append note to output archive metadata (optional).                   | 1                | 1                | 3                |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

------------
``unstarch``
------------

* Extraction of a ``starch`` archive or attributes.
* BEDOPS :ref:`unstarch` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| (no option)                   | NA                                                                   | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--archive-type``            | Show archive's compression type (either ``bzip2`` or ``gzip``).      | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--archive-version``         | Show archive version (at this time, either 1.x or 2.x).              | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--archive-timestamp``       | Show archive creation timestamp (ISO 8601 format).                   | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bases <chromosome>``      | Show total, non-unique base counts for optional ``<chromosome>``     | 1                | 1                | NA               |
|                               | (omitting ``<chromosome>`` shows total non-unique base count).       |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bases-uniq <chromosome>`` | Show unique base counts for optional ``<chromosome>`` (omitting      | 1                | 1                | NA               |
|                               | ``<chromosome>`` shows total, unique base count).                    |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``<chromosome>``              | Decompress information for a single ``<chromosome>`` only.           | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--elements <chromosome>``   | Show element count for optional ``<chromosome>`` (omitting           | 1                | 1                | NA               |
|                               | ``<chromosome>`` shows total element count).                         |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--list`` or ``--list-json`` | Print the metadata for a ``starch`` file, either in tabular form or  | 1                | 1                | NA               |
|                               | with JSON formatting.                                                |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--list-chr`` or             | List all chromosomes in ``starch`` archive (similar to               | 1                | 1                | NA               |
| ``--list-chromosomes``        | ``bedextract --list-chr``).                                          |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--note``                    | Show descriptive note (if originally added to archive).              | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--sha1-signature``          | Show SHA1 signature of JSON-formatted metadata (Base64-encoded).     | 1                | 1                | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

-------------
``starchcat``
-------------

* Merge multiple ``starch`` archive inputs into one ``starch`` archive output.
* BEDOPS :ref:`starchcat` documentation.

+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| option                        | description                                                          | min. file inputs | max. file inputs | min. BED columns |
+===============================+======================================================================+==================+==================+==================+
| (no option)                   | NA                                                                   | 1                | No imposed limit | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--bzip2`` or ``--gzip``     | The internal compression method. The default ``--bzip2`` method      | 1                | No imposed limit | NA               |
|                               | favors storage efficiency, while ``--gzip`` favors compression and   |                  |                  |                  |
|                               | extraction time performance.                                         |                  |                  |                  |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+
| ``--note="foo bar..."``       | Append note to output archive metadata (optional).                   | 1                | No imposed limit | NA               |
+-------------------------------+----------------------------------------------------------------------+------------------+------------------+------------------+

.. |--| unicode:: U+2013   .. en dash
.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
   :trim: