diff clipkit_repo/docs/advanced/index.rst @ 0:49b058e85902 draft

"planemo upload for repository https://github.com/jlsteenwyk/clipkit commit cbe1e8577ecb1a46709034a40dff36052e876e7a-dirty"

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/clipkit_repo/docs/advanced/index.rst	Fri Mar 25 13:04:31 2022 +0000
@@ -0,0 +1,155 @@
+Advanced Usage
+==============
+
+^^^^^
+
+This section describes the various features and options of ClipKIT.
+
+- Modes_
+- Output_
+- Log_
+- Complementary_
+- `All options`_
+
+|
+
+.. _Modes:
+
+Modes
+-----
+
+Herein, we describe the various trimming modes implemented in ClipKIT. If you are unsure which is appropriate for you,
+**we recommend using the default smart-gap trimming mode**. 
+
+ClipKIT can be run with eight different modes, which are specified with the -m/--mode argument.
+*Default: 'smart-gap'*
+
+* smart-gap: dynamic determination of gaps threshold
+* gappy: trim all sites that are above a threshold of gappyness (default: 0.9)
+* kpic: keep only parismony informative and constant sites
+* kpic-smart-gap: a combination of kpic- and smart-gap-based trimming 
+* kpic-gappy: a combination of kpic- and gappy-based trimming
+* kpi: keep only parsimony informative sites
+* kpi-smart-gap: a combination of kpi- and smart-gap-based trimming
+* kpi-gappy: a combination of kpi- and gappy-based trimming
+
+.. code-block:: shell
+
+	# smart-gap-based trimming
+	clipkit <input>
+	clipkit -m smart-gap
+
+	# gappy-based trimming
+	clipkit <input> -m gappy
+
+	# kpic-based trimming
+	clipkit <input> -m kpic
+
+	# kpic- and smart-gap-based trimming
+	clipkit <input> -m kpic-smart-gap
+
+	# kpic- and gappy-based trimming
+	clipkit <input> -m kpic-gappy
+
+	# kpi-based trimming
+	clipkit <input> -m kpi
+
+	# kpi- and smart-gap-based trimming
+	clipkit <input> -m kpi-smart-gap
+
+	# kpi- and gappy-based trimming
+	clipkit <input> -m kpi-gappy
+
+.. _Output:
+
+|
+
+Output
+------
+
+By default, output files will have the same name as the input file with the suffix ".clipkit"
+appended to the name. Users can specify output file names with the -o option. 
+
+.. code-block:: shell
+
+	# specify output
+	clipkit <input> -o <output>
+
+|
+
+.. _Log:
+
+Log
+---
+It can be very useful to have information about the each position in an alignment. For
+example, this information could be used in alignment diagnostics, fine-tuning of trimming
+parameters, etc. To create the log file, use the -l/\\-\\-log option. Using this option
+will create a four column file with the suffix 'clipkit.log'. *Default: off*
+
+* col1: position in the alignment (starting at 1)
+* col2: reports if site was trimmed or kept (trim or keep, respectively)
+* col3: reports if the site is parsimony informative or not (PI or nPI, respectively)
+* col4: reports the gappyness of the position (number of gaps / entries in alignment)
+
+.. code-block:: shell
+
+	clipkit <input> -l 
+
+|
+
+.. _Complementary:
+
+Complementary
+-------------
+
+Having an alignment of the sequences that were trimmed can be useful for other analyses. 
+To obtain an alignment of the sequences that were trimmed, use the -c/\\-\\-complementary 
+option.
+
+.. code-block:: shell
+
+	clipkit <input> -c
+
+Output file with the suffix '.clipkit.complementary'
+
+|
+
+.. _`All options`:
+
+All options
+---------------------
+
+
++-----------------------------+-------------------------------------------------------------------+
+| Option                      | Usage and meaning                                                 |
++=============================+===================================================================+
+| -h/\-\-help                 | Print help message                                                |
++-----------------------------+-------------------------------------------------------------------+
+| -v/\-\-version              | Print software version                                            |
++-----------------------------+-------------------------------------------------------------------+
+| -m/\-\-mode                 | Specify trimming mode (default: smart-gap)                        |
++-----------------------------+-------------------------------------------------------------------+
+| -o/\-\-output               | Specify output file name                                          |
++-----------------------------+-------------------------------------------------------------------+
+| -g/\-\-gaps                 | Specify gappyness threshold (between 0 and 1). *Default: 0.9*     |
++-----------------------------+-------------------------------------------------------------------+
+| -if/\-\-input_file_format   | Specify input file format*. *Default: auto-detect*                |
++-----------------------------+-------------------------------------------------------------------+
+| -of/\-\-output_file_format  | Specify output file format*. *Default: input file type*           |
++-----------------------------+-------------------------------------------------------------------+
+| -l/\-\-log                  | Create a log file. *Default: off*                                 |
++-----------------------------+-------------------------------------------------------------------+
+| -c/--complementary          | Create a complementary alignment file. *Default: off*             |
++-----------------------------+-------------------------------------------------------------------+
+
+
+\*Acceptable file formats include: 
+`fasta <https://en.wikipedia.org/wiki/FASTA_format>`_,
+`clustal <http://meme-suite.org/doc/clustalw-format.html>`_,
+`maf <http://www.bx.psu.edu/~dcking/man/maf.xhtml>`_,
+`mauve <http://darlinglab.org/mauve/user-guide/files.html>`_,
+`phylip <http://scikit-bio.org/docs/0.2.3/generated/skbio.io.phylip.html>`_,
+`phylip-sequential <http://rosalind.info/glossary/phylip-format/>`_,
+`phylip-relaxed <https://www.hiv.lanl.gov/content/sequence/FORMAT_CONVERSION/FormatExplain.html>`_,
+`stockholm <https://en.wikipedia.org/wiki/Stockholm_format>`_
+