Update README.md

Author: martin-steinegger

README.md

@@ -7,6 +7,8 @@ MMseqs2 (Many-against-Many sequence searching) is a software suite to search and
 
 [Steinegger M and Soeding J. Clustering huge protein sequence sets in linear time. Nature Communications, doi: 10.1038/s41467-018-04964-5 (2018)](https://www.nature.com/articles/s41467-018-04964-5).
 
+[Mirdita M, Steinegger M and Soeding J. MMseqs2 desktop and local web server app for fast, interactive sequence searches. Bioinformatics, doi: 10.1093/bioinformatics/bty1057 (2019)](https://academic.oup.com/bioinformatics/article/35/16/2856/5280135)
+
 [![BioConda Install](https://img.shields.io/conda/dn/bioconda/mmseqs2.svg?style=flag&label=BioConda%20install)](https://anaconda.org/bioconda/mmseqs2)
 [![Github All Releases](https://img.shields.io/github/downloads/soedinglab/mmseqs2/total.svg)](https://github.com/soedinglab/mmseqs2/releases/latest)
 [![Docker Pulls](https://img.shields.io/docker/pulls/soedinglab/mmseqs2.svg)](https://hub.docker.com/r/soedinglab/mmseqs2)
@@ -17,25 +19,18 @@ MMseqs2 (Many-against-Many sequence searching) is a software suite to search and
 <p align="center"><img src="https://raw.githubusercontent.com/soedinglab/mmseqs2/master/.github/mmseqs2_logo.png" height="256" /></p>
 
 
-## Documentation 
+## Documentation
 The MMseqs2 user guide is available in our [GitHub Wiki](https://github.com/soedinglab/mmseqs2/wiki) or as a [PDF file](https://mmseqs.com/latest/userguide.pdf) (Thanks to [pandoc](https://github.com/jgm/pandoc)!). We provide a tutorial of MMseqs2 [here](https://github.com/soedinglab/metaG-ECCB18-partII).
 
-## News
 Keep posted about MMseqs2/Linclust updates by following Martin on [Twitter](https://twitter.com/thesteinegger).
 
-08/10/2018 ECCB18 tutorial of MMseqs2 is available [here](https://github.com/soedinglab/metaG-ECCB18-partII).
-
-07/07/2018 Linclust has just been published at [Nature Communications](https://www.nature.com/articles/s41467-018-04964-5).
-
-17/10/2017 MMseqs2 has just been published at [Nature Biotechnology](https://www.nature.com/nbt/journal/vaop/ncurrent/full/nbt.3988.html).
-
 ## Installation
 MMseqs2 can be used by compiling from source, downloading a statically compiled version, using [Homebrew](https://github.com/Homebrew/brew), [conda](https://github.com/conda/conda) or [Docker](https://github.com/moby/moby). MMseqs2 requires a 64-bit system (check with `uname -a | grep x86_64`) with at least the SSE4.1 instruction set (check by executing `cat /proc/cpuinfo | grep sse4_1` on Linux or `sysctl -a | grep machdep.cpu.features | grep SSE4.1` on MacOS).
 
      # install by brew
      brew install mmseqs2
      # install via conda
-     conda install -c bioconda mmseqs2 
+     conda install -c bioconda mmseqs2
      # install docker
      docker pull soedinglab/mmseqs2
      # static build with SSE4.1
@@ -55,130 +50,88 @@ MMseqs2 comes with a bash command and parameter auto completion, which can be ac
 </pre>
          
 ### Compilation from source
-Compiling MMseqs2 from source has the advantage that it will be optimized to the specific system, which should improve its performance. To compile MMseqs2 `git`, `g++` (4.8 or later) and `cmake` (3.0 or later) are needed. Afterwards, the MMseqs2 binary will be located in the `build/bin/` directory.
+Compiling MMseqs2 from source has the advantage that it will be optimized to the specific system, which should improve its performance. To compile MMseqs2 `git`, `g++` (4.8 or later) and `cmake` (2.8.12 or later) are needed. Afterwards, the MMseqs2 binary will be located in the `build/bin/` directory.
 
         git clone https://github.com/soedinglab/MMseqs2.git
         cd MMseqs2
         mkdir build
         cd build
         cmake -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_INSTALL_PREFIX=. ..
         make -j 4
-        make install 
+        make install
         export PATH=$(pwd)/bin/:$PATH
 
 :exclamation: To compile MMseqs2 on MacOS, first install the `gcc` compiler from Homebrew. The default MacOS `clang` compiler does not support OpenMP and MMseqs2 will only be able to use a single thread. Then use the following `cmake` call:
 
         CC="$(brew --prefix)/bin/gcc-9" CXX="$(brew --prefix)/bin/g++-9" cmake -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_INSTALL_PREFIX=. ..
                 
-        
-## Easy workflows 
-We provide `easy` workflows to search, taxonomy and cluster. The `easy-search` searches directly with a FASTA/FASTQ files against a either another FASTA/FASTQ file or an already existing MMseqs2 database.
-        
-        mmseqs easy-search examples/QUERY.fasta DB.fasta alnRes tmp 
- 
-It is also possible to precompute the index for the target database:
 
-        mmseqs createdb examples/DB.fasta targetDB
-        mmseqs createindex targetDB tmp
-        mmseqs easy-search examples/QUERY.fasta targetDB alnRes tmp 
+## Getting started
+We provide `easy` workflows to cluster, search and assign taxonomy. These `easy` workflows are a shorthand to deal directly with FASTA/FASTQ files as input and output. MMseqs2 provides many modules to transform, filter, execute external programs and search. However, these modules use the MMseqs2 database formats, instead of the FASTA/FASTQ format. For maximum flexibility, we recommend using MMseqs2 workflows and modules directly. Please read more about this in the [documentation](https://github.com/soedinglab/mmseqs2/wiki).
+
+### Cluster
 
 For clustering, MMseqs2 `easy-cluster` and `easy-linclust` are available.
 
 `easy-cluster` by default clusters the entries of a FASTA/FASTQ file using a cascaded clustering algorithm.
 
-        mmseqs easy-cluster examples/DB.fasta clusterRes tmp         
+        mmseqs easy-cluster examples/DB.fasta clusterRes tmp --min-seq-id 0.5 -c 0.8 --cov-mode 1        
 
 `easy-linclust` clusters the entries of a FASTA/FASTQ file. The runtime scales linearly with input size. This mode is recommended for huge datasets.
 
         mmseqs easy-linclust examples/DB.fasta clusterRes tmp     
-        
-These `easy` workflows are a shorthand to deal directly with FASTA/FASTQ files as input and output. MMseqs2 provides many modules to transform, filter, execute external programs and search. However, these modules use the MMseqs2 database formats, instead of the FASTA/FASTQ format. For maximum flexibility, we recommend using MMseqs2 workflows and modules directly.
-       
-## How to search
-You can use the query database "QUERY.fasta" and target database "DB.fasta" in the examples folder to test the search workflow. First, you need to convert the FASTA files into the MMseqs2 database format.
+                
+Sequence identity is in default [estimated](https://github.com/soedinglab/MMseqs2/wiki#how-does-mmseqs2-compute-the-sequence-identity) to output real sequence identity use `--alignment-mode 3`.
+Read more about the [clustering format](https://github.com/soedinglab/mmseqs2/wiki#clustering-format) in our user guide.
+                
+Please adjust the [clustering criteria](https://github.com/soedinglab/MMseqs2/wiki#clustering-criteria) and check if temporary directory provides enough free space. For disk space requirements, see the user guide.
 
-        mmseqs createdb examples/QUERY.fasta queryDB
-        mmseqs createdb examples/DB.fasta targetDB
+### Search
+         
+The `easy-search` searches directly with a FASTA/FASTQ files against either another FASTA/FASTQ file or an already existing MMseqs2 database.
 
-If the target database is going to be used several times, we recommend precomputing an index of `targetDB` as this saves overhead computations.
+        mmseqs easy-search examples/QUERY.fasta DB.fasta alnRes tmp
+ 
+It is also possible to pre-compute the index for the target database:
 
+        mmseqs createdb examples/DB.fasta targetDB
         mmseqs createindex targetDB tmp
+        mmseqs easy-search examples/QUERY.fasta targetDB alnRes tmp
+        
+The speed and sensitivity of the `search` can be adjusted with `-s` parameter and should be adapted based on your use case (see [setting sensitivity -s parameter](https://github.com/soedinglab/mmseqs2/wiki#set-sensitivity--s-parameter)). A very fast search would use a sensitivity of `-s 1.0`, while a very sensitive search would use a sensitivity of up to `-s 7.0`. A detailed guide how to speed up searches is [here](https://github.com/soedinglab/MMseqs2/wiki#how-to-control-the-speed-of-the-search).
 
-MMseqs2 stores intermediate results in `tmp`. Using a fast local drive can reduce load on a shared filesystem and increase speed.
-
-To run the search, execute:
-
-        mmseqs search queryDB targetDB resultDB tmp
-
-The speed and sensitivity of the `search` can be adjusted with `-s` parameter and should be adapted based on your use case (see [setting sensitivity -s parameter](https://github.com/soedinglab/mmseqs2/wiki#set-sensitivity--s-parameter)). A very fast search would use a sensitivity of `-s 1.0`, while a very sensitive search would use a sensitivity of up to `-s 7.0`.
-
-If you require the exact alignment information (Sequence identity, alignment string, ...) in later steps add the option `-a` parameter, without this parameter MMseqs2 will automatically decide if only the score needs to be computed or the exact alignment to optimize computation time.
-
-Please ensure that, in case of large input databases, the `tmp` directory provides enough free space.
-Our user guide provides information on [disk space requirements](https://github.com/soedinglab/mmseqs2/wiki#prefiltering-module).
+The output can be customized with the `--format-output` option e.g. `--format-output "query,target,qaln,taln"` returns the query and target accession and the pairwise alignments in tab separated format. You can choose many different [output columns](https://github.com/soedinglab/mmseqs2/wiki#custom-alignment-format-with-convertalis).
 
-Then convert the result database into a BLAST-tab formatted database (format: qId, tId, seqIdentity, alnLen, mismatchCnt, gapOpenCnt, qStart, qEnd, tStart, tEnd, eVal, bitScore).
+### Taxonomy
+The `easy-taxonomy` workflow can be used assign sequences taxonomical labels. It performs a search against a target sequence databases and computes the lowest common ancestor of all equal scoring top hits (default). Other assignment options are available through `--lca-mode`.
 
-        mmseqs convertalis queryDB targetDB resultDB resultDB.m8
+        mmseqs createdb examples/DB.fasta targetDB
+        mmseqs createtaxdb targetDB tmp
+        mmseqs createindex targetDB tmp
+        mmseqs easy-taxonomy examples/QUERY.fasta targetDB alnRes tmp
 
-The output can be customized with the `--format-output` option e.g. `--format-output "query,target,qaln,taln"` returns the query and target accession and the pairwise alignments in tab separated format. You can choose many different [output columns](https://github.com/soedinglab/mmseqs2/wiki#custom-alignment-format-with-convertalis) in the `convertalis` module. Make sure that you used the option `-a` during the search (`mmseqs search ... -a`).
+In default `createtaxdb` assigns every sequence with a Uniprot accession to a taxonomical identifier and downloads the NCBI taxonomy. We also support [BLAST](https://github.com/soedinglab/MMseqs2/wiki#create-a-sequence-database-with-taxonomic-information-from-an-existing-blast-database), [SILVA](https://github.com/soedinglab/MMseqs2/wiki#create-a-sequence-database-with-taxonomic-information-for-silva) or [custom taxonomical](https://github.com/soedinglab/MMseqs2/wiki#manually-annotate-a-sequence-database-with-taxonomic-information) databases.
 
-        mmseqs convertalis queryDB targetDB resultDB resultDB.pair --format-output "query,target,qaln,taln"
+Read more about the [taxonomy format](https://github.com/soedinglab/MMseqs2/wiki#taxonomy-format) and the [classification](https://github.com/soedinglab/MMseqs2/wiki#taxonomy-assignment-using-mmseqs-taxonomy) in our user guide.
 
-### Other search modes
+### Supported search modes
 
 MMseqs2 provides many additional search modes:
  * Iterative sequences-profile searches (like PSI-BLAST) with the `--num-iterations` parameter
  * [Translated searches](https://github.com/soedinglab/MMseqs2/wiki#translated-sequence-searching) of nucleotides against proteins (blastx), proteins against nucleotides (tblastn) or nucleotide against nucleotide (tblastx)
  * [Iterative increasing sensitivity searches](https://github.com/soedinglab/MMseqs2/wiki#how-to-find-the-best-hit-the-fastest-way) to find only the best hits faster
  * [Taxonomic assignment](https://github.com/soedinglab/MMseqs2/wiki#taxonomy-assignment-using-mmseqs-taxonomy) using 2bLCA or LCA
  * Fast ungapped alignment searches to find [very similar sequence matches](https://github.com/soedinglab/MMseqs2/wiki#mapping-very-similar-sequences-using-mmseqs-map)
- * Very fast and sensitive Searches against [profile databases such as the PFAM](https://github.com/soedinglab/MMseqs2/wiki#how-to-create-a-target-profile-database-from-pfam)
+ * Very fast and sensitive searches against [profile databases such as the PFAM](https://github.com/soedinglab/MMseqs2/wiki#how-to-create-a-target-profile-database-from-pfam)
  * [Reciprocal best hits search](https://github.com/soedinglab/MMseqs2/wiki#reciprocal-best-hit-using-mmseqs-rbh)
  * [Web search API and user interface](https://github.com/soedinglab/MMseqs2-App)
 
-
 Many modes can also be combined. You can, for example, do a translated nucleotide against protein profile search.
 
-## How to cluster 
-Before clustering, convert your database into the MMseqs2 database format:
-
-        mmseqs createdb examples/DB.fasta DB
-
-Then execute the clustering:
-
-        mmseqs cluster DB clu tmp
-        
-or linear time clustering (faster but less sensitive):
-
-        mmseqs linclust DB clu tmp
-
-Please adjust the [clustering criteria](https://github.com/soedinglab/MMseqs2/wiki#clustering-criteria) and check if temporary directory provides enough free space. For disk space requirements, see the user guide.
-
-To generate a FASTA-style formatted output file from our MMseqs2 databases, type:
-
-        mmseqs createseqfiledb DB clu clu_seq 
-        mmseqs result2flat DB DB clu_seq clu_seq.fasta
-        
-To generate a TSV-style formatted output file from our MMseqs2 databases, type:
-
-        mmseqs createtsv DB DB clu clu.tsv
-        
-To extract the representative sequences from the clustering result call:    
-    
-        mmseqs result2repseq DB clu DB_clu_rep
-        mmseqs result2flat DB DB DB_clu_rep DB_clu_rep.fasta --use-fasta-header
-
-Read more about the [clustering format](https://github.com/soedinglab/mmseqs2/wiki#clustering-format) in our user guide.
-
 ### Memory Requirements
-MMseqs2 checks the available system memory and automatically divides the target database in parts that fit into memory. Splitting the database will increase the runtime slightly.
-
-The memory consumption grows linearly with the number of residues in the database. The following formula can be used to estimate the index size.  
-        
-        M = (7 × N × L) byte + (8 × a^k) byte
-
-Where `L` is the average sequence length and `N` is the database size.
+MMseqs2 minimum memory requirements for `cluster` or `linclust` is 1 byte per sequence residue, `search` needs 1 byte per target residue. Sequence databases can be compressed using the `--compress` flag, DNA sequences can be reduced by a factor of `~3.5` and proteins by `~1.7`.
+   
+MMseqs2 checks the available system memory and automatically divides the target database in parts that fit into memory. Splitting the database will increase the runtime slightly. It is possible to control the memory usage using `--split-memory-limit`.
 
 ### How to run MMseqs2 on multiple servers using MPI
 MMseqs2 can run on multiple cores and servers using OpenMP and Message Passing Interface (MPI).
@@ -189,3 +142,5 @@ Make sure that MMseqs2 was compiled with MPI by using the `-DHAVE_MPI=1` flag (`
 To search with multiple servers, call the `search` or `cluster` workflow with the MPI command exported in the RUNNER environment variable. The databases and temporary folder have to be shared between all nodes (e.g. through NFS):
 
         RUNNER="mpirun -pernode -np 42" mmseqs search queryDB targetDB resultDB tmp
+
+