Prepare v 3.2.0 (#11)

Prepare for version 3.2.0 release
refresh-bio · Dec 23, 2021 · cc843b8 · cc843b8
1 parent b4ea128
commit cc843b8
Show file tree

Hide file tree

Showing 109 changed files with 269 additions and 234 deletions.
diff --git a/README.md b/README.md
@@ -2,16 +2,39 @@ KMC
 =
 [![GitHub downloads](https://img.shields.io/github/downloads/refresh-bio/kmc/total.svg?style=flag&label=GitHub%20downloads)](https://github.com/refresh-bio/KMC/releases)
 [![Bioconda downloads](https://img.shields.io/conda/dn/bioconda/kmc.svg?style=flag&label=Bioconda%20downloads)](https://anaconda.org/bioconda/kmc)
+[![GitHub Actions CI](../../actions/workflows/main.yml/badge.svg)](../../actions/workflows/main.yml)
 
-KMC is a disk-based programm for counting k-mers from (possibly gzipped) FASTQ/FASTA files.
-The homepage of the KMC project is http://sun.aei.polsl.pl/kmc
+KMC is a disk-based program for counting k-mers from (possibly gzipped) FASTQ/FASTA files.
+KMC is one of many projects developed by [REFRESH Bioinformatics Group](http://sun.aei.polsl.pl/REFRESH/).
 
 For accessing k-mers stored in database produced by KMC there is an API (kmc_api directory). Note that for KMC versions 0.x and 1.x dababase format differs from produced by KMC version 2.x. From version 2.2.0 API is unified for both formats and all new features/bug fixes are present only for 2.x branch (standalone API for older KMC version is not longer under development, so new version of API  should be used even for databases produced by older KMC version).
 
-Installation
+Quick start
+=
+#### Getting the executable
+The simplest way to get the KMC is to download newest release for appropriate operating system from [KMC releases](https://github.com/refresh-bio/KMC/releases).
+#### Counting the k-mers from a single fastq file
+```
+./kmc -k27 input.fastq 27mers .
+```
+The command above will count all the 27-mers occurring in ```input.fastq``` at least twice (configurable with ```-ci``` switch). 
+The result will be stored in a KMC database, which is split into two files: ```27mers.kmc_pre``` and ```27mers.kmc_suf```.
+KMC will create hundreds of intermediate files. In the case of the above command, those will be created in the current working directory(the ```.``` at the end of the command). 
+It may be more convinient to use dedicated directory for KMC temporary files, for example:
+```
+mkdir kmc_tmp # create directory for kmc temporary files
+./kmc -k27 input.fastq 27mers kmc_tmp
+```
+#### Create text dump from KMC database binary format
+Having the k-mers counted it is possible to dump KMC binary database to textual form with ```kmc_tools```.
+```
+./kmc_tools transform 27mers dump 27mers.txt
+```
+
+Installation details
 =
 The following libraries come with KMC in a binary (64-bit compiled for x86 platform) form.
-If your system needs other binary formats, you should put the following libraries in kmer_counter/libs:
+If your system needs other binary formats, you should put the following libraries in kmc_core/libs:
 * libbzip2 - for support for bzip2-compressed input FASTQ/FASTA files (http://www.bzip.org/)
 * zlib - for support for gzip-compressed input FASTQ/FASTA files (http://www.zlib.net/)
 
@@ -39,12 +62,21 @@ To increase this number use following command before running KMC:
 
 Directory structure
 =
- * bin           - main directory of KMC (programs after compilation will be stored here)
- * kmer_counter  - source code of kmc program
- * kmer_counter/libs - compiled binary versions of libraries used by KMC
- * kmc_api       - C++ source codes implementing API; must be used by any program that wants to process databases produced by kmc
- * kmc_dump      - source codes of kmc_dump program listing k-mers in databases produced by kmc
+ * bin           - after compilation executables and libraries after compilation will be stored here
+ * include       - after compilation header file to use kmc core through the C++ API will be stored here
+ * kmc_core      - source code of kmc core library
+ * kmc_CLI       - source code of kmc command line interface
+ * kmc_tools     - source codes of kmc_tools program
+ * kmc_core/libs - libraries used by KMC
+ * kmc_api       - C++ source codes implementing API to access KMC databases; must be used by any program that wants to process databases produced by kmc
+ * kmc_dump      - source codes of kmc_dump program listing k-mers in databases produced by kmc (deprecated, use kmc_tools instead)
  * py_kmc_api    - python wrapper for kmc API
+ * tests         - tests files
+
+Use the KMC directly from code through the API
+=
+It is possible to use the KMC directly from C++ code through.
+Detailed API description is available at [wiki](https://github.com/refresh-bio/KMC/wiki/Use-the-KMC-directly-from-code-through-the-API)
 
 Python wrapper for KMC API
 =
@@ -74,15 +106,16 @@ py_kmc_api\set_path.bat
 it will export apropriate file. The example of Python wrapper for KMC API is presented in file:
 py_kmc_api/py_kmc_dump.py
 
-Detailed API describtion is avaiable at [wiki](https://github.com/refresh-bio/KMC/wiki/Python-wrapper-for-KMC-API)
-
+Detailed API description is available at [wiki](https://github.com/refresh-bio/KMC/wiki/Python-wrapper-for-KMC-API)
 
 Binaries
 =
 After compilation you will obtain two binaries:
 * bin/kmc - the main program for counting k-mer occurrences
 * bin/kmc_dump - the program listing k-mers in a database produced by kmc
 * bin/kmc_tools - the program allowing to manipulate kmc databases (set operations, transformations, etc.)
+* bin/libkmc_core.a - compiled KMC code sources
+* py_kmc_api.cpython-39-x86_64-linux-gnu.so - compiled python wrapper for KMC API
 
 
 License
@@ -105,3 +138,9 @@ TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DI
 THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+## Citing
+[Marek Kokot, Maciej Długosz, Sebastian Deorowicz, KMC 3: counting and manipulating k-mer statistics, Bioinformatics, Volume 33, Issue 17, 01 September 2017, Pages 2759–2761, https://doi.org/10.1093/bioinformatics/btx304](https://academic.oup.com/bioinformatics/article/33/17/2759/3796399)
+
+[Sebastian Deorowicz, Marek Kokot, Szymon Grabowski, Agnieszka Debudaj-Grabysz, KMC 2: fast and resource-frugal k-mer counting, Bioinformatics, Volume 31, Issue 10, 15 May 2015, Pages 1569–1576, https://doi.org/10.1093/bioinformatics/btv022](https://academic.oup.com/bioinformatics/article/31/10/1569/177467)
+
+[Deorowicz, S., Debudaj-Grabysz, A. & Grabowski, S. Disk-based k-mer counting on a PC. BMC Bioinformatics 14, 160 (2013). https://doi.org/10.1186/1471-2105-14-160](https://bmcbioinformatics.biomedcentral.com/articles/10.1186/1471-2105-14-160)
diff --git a/kmc_api/kmc_file.cpp b/kmc_api/kmc_file.cpp
@@ -4,8 +4,8 @@
 
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include "mmer.h"

diff --git a/kmc_api/kmc_file.h b/kmc_api/kmc_file.h
@@ -4,8 +4,8 @@
 
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
  */
 
 #ifndef _KMC_FILE_H

diff --git a/kmc_api/kmer_api.cpp b/kmc_api/kmer_api.cpp
@@ -4,8 +4,8 @@
 
   Authors: Sebastian Deorowicz and Agnieszka Debudaj-Grabysz
 
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include "kmer_api.h"

diff --git a/kmc_api/kmer_api.h b/kmc_api/kmer_api.h
@@ -4,8 +4,8 @@ The homepage of the KMC project is http://sun.aei.polsl.pl/kmc
 
 Authors: Sebastian Deorowicz and Agnieszka Debudaj-Grabysz
 
-Version: 3.1.1
-Date   : 2019-05-19
+Version: 3.2.0
+Date   : 2021-12-23
 */
 
 #ifndef _KMER_API_H

diff --git a/kmc_api/kmer_defs.h b/kmc_api/kmer_defs.h
@@ -4,8 +4,8 @@
 
   Authors: Sebastian Deorowicz and Agnieszka Debudaj-Grabysz
 
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 
@@ -14,8 +14,8 @@
 
 #include <cinttypes>
 
-#define KMC_VER		"3.1.1"
-#define KMC_DATE	"2019-05-19"
+#define KMC_VER		"3.2.0"
+#define KMC_DATE	"2021-12-23"
 
 #ifndef MIN
 #define MIN(x,y)	((x) < (y) ? (x) : (y))

diff --git a/kmc_api/mmer.cpp b/kmc_api/mmer.cpp
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include "../kmc_api/mmer.h"

diff --git a/kmc_api/mmer.h b/kmc_api/mmer.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _MMER_H

diff --git a/kmc_api/stdafx.h b/kmc_api/stdafx.h
diff --git a/kmc_core/bam_utils.h b/kmc_core/bam_utils.h
@@ -4,8 +4,8 @@ The homepage of the KMC project is http://sun.aei.polsl.pl/kmc
 
 Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-Version: 3.1.1
-Date   : 2019-05-19
+Version: 3.2.0
+Date   : 2021-12-23
 */
 
 #ifndef _BAM_UTILS_H

diff --git a/kmc_core/binary_reader.h b/kmc_core/binary_reader.h
@@ -4,8 +4,8 @@ The homepage of the KMC project is http://sun.aei.polsl.pl/kmc
 
 Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-Version: 3.1.1
-Date   : 2019-05-19
+Version: 3.2.0
+Date   : 2021-12-23
 */
 
 #ifndef _BINARY_READER_H

diff --git a/kmc_core/bkb_merger.h b/kmc_core/bkb_merger.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _HBH_MERGER_H

diff --git a/kmc_core/bkb_reader.cpp b/kmc_core/bkb_reader.cpp
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include "bkb_reader.h"

diff --git a/kmc_core/bkb_reader.h b/kmc_core/bkb_reader.h
@@ -5,8 +5,8 @@ The homepage of the KMC project is http://sun.aei.polsl.pl/kmc
 
 Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-Version: 3.1.1
-Date   : 2019-05-19
+Version: 3.2.0
+Date   : 2021-12-23
 */
 
 #ifndef _BKB_READER_H_

diff --git a/kmc_core/bkb_sorter.h b/kmc_core/bkb_sorter.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _BKB_SORTER_H

diff --git a/kmc_core/bkb_subbin.h b/kmc_core/bkb_subbin.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _BKB_SUBBIN_H

diff --git a/kmc_core/bkb_uncompactor.h b/kmc_core/bkb_uncompactor.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _BKB_UNCOMPACTOR_H

diff --git a/kmc_core/bkb_writer.cpp b/kmc_core/bkb_writer.cpp
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include "bkb_writer.h"

diff --git a/kmc_core/bkb_writer.h b/kmc_core/bkb_writer.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _BKB_WRITER_H

diff --git a/kmc_core/cpu_info.cpp b/kmc_core/cpu_info.cpp
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include "cpu_info.h"

diff --git a/kmc_core/cpu_info.h b/kmc_core/cpu_info.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _CPU_INFO_

diff --git a/kmc_core/defs.h b/kmc_core/defs.h
@@ -4,17 +4,17 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _DEFS_H
 #define _DEFS_H
 
 #include <cinttypes>
 
-#define KMC_VER		"3.1.1"
-#define KMC_DATE	"2019-05-19"
+#define KMC_VER		"3.2.0"
+#define KMC_DATE	"2021-12-23"
 
 #define _CRT_SECURE_NO_WARNINGS
 

diff --git a/kmc_core/fastq_reader.cpp b/kmc_core/fastq_reader.cpp
@@ -4,8 +4,8 @@
 
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #include <algorithm>

diff --git a/kmc_core/fastq_reader.h b/kmc_core/fastq_reader.h
@@ -4,8 +4,8 @@
   
   Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
   
-  Version: 3.1.1
-  Date   : 2019-05-19
+  Version: 3.2.0
+  Date   : 2021-12-23
 */
 
 #ifndef _FASTQ_READER_H

diff --git a/kmc_core/first_dispatch.h b/kmc_core/first_dispatch.h
@@ -4,8 +4,8 @@ The homepage of the KMC project is http://sun.aei.polsl.pl/kmc
 
 Authors: Sebastian Deorowicz, Agnieszka Debudaj-Grabysz, Marek Kokot
 
-Version: 3.1.1
-Date   : 2019-05-19
+Version: 3.2.0
+Date   : 2021-12-23
 */
 #ifndef _FIRST_DISPATCH_H
 #define _FIRST_DISPATCH_H
@@ -85,13 +85,13 @@ class CRangeQueue
 			return true;
 		}
 		return false;
-		//TODO: dodaæ obs³ugê badania poprawnych danych, tzn przynajmniej jednego rekordu
+		//TODO: doda� obs�ug� badania poprawnych danych, tzn przynajmniej jednego rekordu
 	}
 
 	void reset_indices()
 	{
 		cur_idx = 0;
-		done = false;  //TODO: dodaæ obs³ugê badania poprawnych danych
+		done = false;  //TODO: doda� obs�ug� badania poprawnych danych
 	}
 };