diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..4ee7934 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,238 @@ +

+ + Logo + +

+ Docs + · + Report Bug + · + Request Feature +

+

+ + + + + + + + + + + + + + + + + follow on Twitter + +

+

+ +ClipKIT is a fast and flexible alignment trimming tool that keeps phylogenetically informative sites and removes others.

+If you found clipkit useful, please cite *ClipKIT: a multiple sequence alignment trimming software for accurate phylogenomic inference*. bioRxiv. doi: [10.1101/2020.06.08.140384](https://www.biorxiv.org/content/10.1101/2020.06.08.140384v1). +

+ + +--- + + +## Guide +[Quick Start](#quick-start)
+[Advanced Usage](#advanced-usage)
+[Performance Assessment](#performance-assessment)
+[FAQ](#faq) + + +--- + +## Quick Start +### 1) Installation +To install, use the following commands: +```shell +pip install clipkit +``` +
+ +To install from source, use the following commands: +```shell +git clone https://github.com/JLSteenwyk/ClipKIT.git +cd ClipKIT/ +make install +``` +
+ +If you run into permission errors when executing *make install*, create a virtual environment for your installation: +```shell +git clone https://github.com/JLSteenwyk/ClipKIT.git +cd ClipKIT/ +python -m venv venv +source venv/bin/activate +make install +``` +Note, the virtual environment must be activated to use clipkit. +
+ +### 2) Usage +To use ClipKIT in its simpliest form, execute the following command: +``` +clipkit +``` +Output file with the suffix ".clipkit" + +
+ +--- + +### Advanced Usage +This section describes the various features and options of ClipKIT.
+\- [Modes](#modes)
+\- [Output](#output)
+\- [Log](#log)
+\- [Complementary](#complementary)
+\- [All options](#all-options) + +
+ +### Modes +ClipKIT can be run with five different modes (gappy, kpic, kpic-gappy, kpi, and kpi-gappy), which are specified with the -m/--mode argument.
+*Default: 'gappy'*
+* gappy: trim all sites that are above a threshold of gappyness (default: 0.9)
+* kpic (alias: medium): keep only parismony informative and constant sites
+* kpic-gappy (alias: medium-gappy): a combination of kpic- and gappy-based trimming
+* kpi (alias: heavy): keep only parsimony informative sites
+* kpi-gappy (alias: heavy-gappy): a combination of kpi- and gappy-based trimming
+``` +# gappy-based trimming +clipkit +clipkit -m gappy + +# kpic-based trimming +clipkit -m kpic +clipkit -m medium + +# kpic- and gappy-based trimming +clipkit -m kpic-gappy +clipkit -m medium-gappy + +# kpi-based trimming +clipkit -m kpi +clipkit -m heavy + +# kpi- and gappy-based trimming +clipkit -m kpi-gappy +clipkit -m heavy-gappy +``` + +
+ +### 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. + +``` +# specify output +clipkit -o +``` + +
+ +### 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 constant or not (Const or nConst), parsimony informative or not (PI or nPI), or neither (nConst, nPI) +* col4: reports the gappyness of the position (number of gaps / entries in alignment) +
+ +``` +clipkit -l +``` +Output file with the suffix ".clipkit.log" + +
+ +### 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. +*Default: off*
+ +``` +clipkit -c +``` +Output file with the suffix ".clipkit.complementary" + +
+ +### All options +| Option | Usage and meaning | +| ------------- | ------------------ | +| -h/--help | Print help message | +| -v/--version | Print software version | +| -o/--output | Specify output file name | +| -m/--modes | Specify trimming mode. *Default: gappy* | +| -g/--gaps | Specify gappyness threshold (between 0 and 1). *Default: 0.9* | +| -if/--input_file_format | Specify input file format*. *Default: auto-detect* | +| -of/--input_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) +
+
+ +--- + +## Performance Assessment +In brief, performance assessment and comparison of multiple trimming alignment software revealed that ClipKIT with nearly any mode is a top-performing software. Here, we provide greater detail into the empirical datasets used to assess alignment trimming performance. +

+ + Performance Summary + +

+ +**ClipKIT is a top-performing software for trimming multiple sequence alignments.** Across a total of 138,152 multiple sequence alignments (MSAs) from empirical (left) and simulated (right) datasets, desirability-based integration of accuracy and support metrics per MSA facilitated the comparison of relative software performance and revealed ClipKIT is a top-performing software. MSA trimming approaches are ordered along the x-axis from the highest-performing software to the lowest-performing software according to average desirability-based rank. Abbreviations of trimmers and parameters are as follows: ClipKIT: g = gappy mode; ClipKIT: kc = kpic; ClipKIT: kcg = kpic-gappy; ClipKIT: k = kpi mode; ClipKIT: kg = kpi-gappy mode; BMGE = BMGE default; BMGE 0.3 = 0.3 entropy threshold; BMGE 0.7 = 0.7 entropy threshold; trimAl: s = strict; trimAl: sp = strictplus; Noisy = default; Gblocks = default; No trim = no trimming. + +For additional performance details, please see the manuscript *ClipKIT: a multiple sequence alignment trimming software for accurate phylogenomic inference*. PLOS Biology. doi: [10.1101/2020.06.08.140384](https://jlsteenwyk.com/publication_pdfs/2020_Steenwyk_etal_PLOS_Biology.pdf). + +


+ +--- + +## FAQ + +If tree inference with no trim works well, why even trim? + +Tree inference with trimmed multiple sequence alignments is computationally efficient. In other words, shorter alignments require less computational time and memory during tree search. We found that ClipKIT reduced computation time by an average of 20%. As datasets continuously become bigger, an alignment trimming algorithm that can reduce computational time will be of great value. + +
+ +Does ClipKIT trim amino acids, nucleotides, or codons? + +ClipKIT's trims amino acid and nucleotide alignments. Currently, ClipKIT does not trim codons. + +
+ +Is there a website version of ClipKIT? + +Currently, there is not website version of ClipKIT. + +
+ +--- + +## Developers +* [Jacob Steenwyk](https://jlsteenwyk.github.io/)
+* [Thomas Buida](https://tjbiii.com)
+
+ +## All Team Members +* [Jacob Steenwyk](https://jlsteenwyk.github.io/)
+* [Thomas Buida](https://tjbiii.com)
+* [Yuanning Li](https://scholar.google.com/citations?user=65ygCIsAAAAJ&hl=en&oi=ao) +* [Xing-Xing Shen](https://xingxingshen.github.io/) +* [Antonis Rokas](https://as.vanderbilt.edu/rokaslab/) +
diff --git a/tests/integration/test_simple_case.py b/tests/integration/test_simple_case.py index ae66502..a92abf6 100644 --- a/tests/integration/test_simple_case.py +++ b/tests/integration/test_simple_case.py @@ -10,7 +10,6 @@ @pytest.mark.integration class TestSimpleCase(object): - @pytest.mark.slow def test_simple_case(self): """ test simple case diff --git a/tests/unit/test_entrypoint.py b/tests/unit/test_entrypoint.py index 33d46c1..d8fa038 100644 --- a/tests/unit/test_entrypoint.py +++ b/tests/unit/test_entrypoint.py @@ -1,13 +1,17 @@ import os import subprocess +import pytest + class TestEntrypoint(object): + @pytest.mark.slow def test_help(self): cmd = "orthohmm --help" exit_status = os.system(cmd) assert exit_status == 0 + @pytest.mark.slow def test_run(self): cmd = "orthohmm tests/samples/" exit_status = os.system(cmd)