{"id":48071108,"url":"https://github.com/refresh-bio/kmer-db","last_synced_at":"2026-04-04T14:42:56.287Z","repository":{"id":29381958,"uuid":"120905793","full_name":"refresh-bio/kmer-db","owner":"refresh-bio","description":"Kmer-db is a fast and memory-efficient tool for large-scale k-mer analyses (indexing, querying, estimating evolutionary relationships, etc.).","archived":false,"fork":false,"pushed_at":"2025-05-20T09:19:14.000Z","size":5875,"stargazers_count":89,"open_issues_count":11,"forks_count":18,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-20T10:31:49.390Z","etag":null,"topics":["bioinformatics","genomics","indexing","k-mer","sequence-similarity"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refresh-bio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-02-09T12:57:04.000Z","updated_at":"2025-05-20T09:17:07.000Z","dependencies_parsed_at":"2022-08-26T12:12:08.916Z","dependency_job_id":"bb4e62cc-064e-4cca-bf6c-a4937dacfd77","html_url":"https://github.com/refresh-bio/kmer-db","commit_stats":{"total_commits":157,"total_committers":7,"mean_commits":"22.428571428571427","dds":0.08280254777070062,"last_synced_commit":"04f2dd420ea1bb3de263e4753f4cbc154e32b925"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/refresh-bio/kmer-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refresh-bio%2Fkmer-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refresh-bio%2Fkmer-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refresh-bio%2Fkmer-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refresh-bio%2Fkmer-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refresh-bio","download_url":"https://codeload.github.com/refresh-bio/kmer-db/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refresh-bio%2Fkmer-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","genomics","indexing","k-mer","sequence-similarity"],"created_at":"2026-04-04T14:42:55.730Z","updated_at":"2026-04-04T14:42:56.281Z","avatar_url":"https://github.com/refresh-bio.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kmer-db\n[![GitHub downloads](https://img.shields.io/github/downloads/refresh-bio/kmer-db/total.svg?style=flag\u0026label=GitHub%20downloads)](https://github.com/refresh-bio/kmer-db/releases)\n[![Bioconda downloads](https://img.shields.io/conda/dn/bioconda/kmer-db.svg?style=flag\u0026label=Bioconda%20downloads)](https://anaconda.org/bioconda/kmer-db)\n[![Build and tests](../../workflows/Build%20and%20tests/badge.svg)](../../actions/workflows/main.yml)\n[![License](https://anaconda.org/bioconda/famsa/badges/license.svg)](https://www.gnu.org/licenses/gpl-3.0.html)\n\n![x86-64](https://img.shields.io/static/v1?label=%E2%80%8B\u0026message=x86-64\u0026color=yellow\u0026logo=PCGamingWiki\u0026logoColor=white)\n![ARM](https://img.shields.io/static/v1?label=%E2%80%8B\u0026message=ARM\u0026color=yellow\u0026logo=Raspberry%20Pi\u0026logoColor=white)\n![Apple M](https://img.shields.io/static/v1?label=%E2%80%8B\u0026message=Apple%20M\u0026color=yellow\u0026logo=Apple\u0026logoColor=white)\n![Windows](https://img.shields.io/badge/%E2%80%8B-Windows-00A98F?logo=windows)\n![Linux](https://img.shields.io/static/v1?label=%E2%80%8B\u0026message=Linux\u0026color=00A98F\u0026logo=linux\u0026logoColor=white)\n![macOS](https://img.shields.io/badge/%E2%80%8B-macOS-00A98F?logo=apple)\n\nKmer-db is a fast and memory-efficient tool for large-scale k-mer analyses (indexing, querying, estimating evolutionary relationships, etc.). \n\n## Quick start\n\n```bash\ngit clone --recurse-submodules https://github.com/refresh-bio/kmer-db\ncd kmer-db \u0026\u0026 gmake\n\nINPUT=./test/virus\nOUTPUT=./output\nmkdir $OUTPUT\n\n# build a database from all 18-mers (default) contained in a set of sequences\n./bin/kmer-db build $INPUT/seqs.part1.list $OUTPUT/k18.db\n\n# establish numbers of common k-mers between new sequences and the database\n./bin/kmer-db new2all $OUTPUT/k18.db $INPUT/seqs.part2.list $OUTPUT/n2a.csv\n\n# calculate jaccard index from common k-mers\n./bin/kmer-db distance jaccard $OUTPUT/n2a.csv $OUTPUT/n2a.jaccard\n\n# extend the database with new sequences\n./bin/kmer-db build -extend $INPUT/seqs.part2.list $OUTPUT/k18.db\n\n# establish numbers of common k-mers between all sequences in the database\n./bin/kmer-db all2all $OUTPUT/k18.db $OUTPUT/a2a.csv\n\n# build a database from 10% of 25-mers using 16 threads\n./bin/kmer-db build -k 25 -f 0.1 -t 16 $INPUT/seqs.part1.list $OUTPUT/k25.db\n\n# establish number of common 25-mers between single sequence and the database \n# (minhash filtering that retains 10% of MT159713 k-mers is done prior to the comparison)  \n./bin/kmer-db one2all $OUTPUT/k25.db $INPUT/data/MT159713.fasta $OUTPUT/MT159713.csv\n\n# build two partial databases\n./bin/kmer-db build $INPUT/seqs.part1.list  $OUTPUT/k18.parts1.db\n./bin/kmer-db build $INPUT/seqs.part2.list  $OUTPUT/k18.parts2.db\n\n# establish numbers of common k-mers between all sequences in the databases,\n# computations are done in the sparse mode, the output matrix is also sparse\necho $OUTPUT/k18.parts1.db \u003e $OUTPUT/db.list\necho $OUTPUT/k18.parts2.db \u003e\u003e $OUTPUT/db.list\n./bin/kmer-db all2all-parts $OUTPUT/db.list $OUTPUT/k18.parts.csv\n\n```\n\n\n### Table of contents\n\n1. [Installation](#1-installation)\n2. [Usage](#2-usage)\n    1. [Building a database](#21-building-a-database)\n    2. [Counting common k-mers](#22-counting-common-k-mers)\n    3. [Calculating similarities or distances](#23-calculating-similarities-or-distances)\n    4. [Storing minhashed k-mers](#24-storing-minhashed-k-mers)\n3. [Datasets](#3-datasets)\n\n\n# 1. Installation\n\nKmer-db comes with a set of [precompiled binaries](https://github.com/refresh-bio/kmer-db/releases) for Linux, macOS, and Windows. \nThe software is also available on [Bioconda](https://anaconda.org/bioconda/kmer-db):\n```\nconda install -c bioconda kmer-db\n```\nFor detailed instructions how to set up Bioconda, please refer to the [Bioconda manual](https://bioconda.github.io/).\nKmer-db can be also built from the sources distributed as:\n\n* GNU Make project for Linux and macOS (gmake 4.3 and gcc/g++ 11 or newer required),\n* Visual Studio 2022 solution for Windows.\n\n\n## Vector extensions\n\nKmer-db can be built for x86-64 and ARM64 8 architectures (including Apple Mx based on ARM64 8.4 core) and takes advantage of AVX2 (x86-64) and NEON (ARM) CPU extensions. The default target platform is x86-64 with AVX2 extensions. This, however, can be changed by setting `PLATFORM` variable for `make`:\n\n```bash\nmake PLATFORM=none    # unspecified platform, no extensions\nmake PLATFORM=sse2    # x86-64 with SSE2 \nmake PLATFORM=avx     # x86-64 with AVX \nmake PLATFORM=avx2    # x86-64 with AVX2 (default)\nmake PLATFORM=native  # x86-64 with AVX2 and native architecture\nmake PLATFORM=arm8    # ARM64 8 with NEON  \nmake PLATFORM=m1      # ARM64 8.4 (especially Apple M1) with NEON \n```   \n\nNote, that x86-64 binaries determine the supported extensions at runtime, which makes them backwards-compatible. For instance, the AVX executable will also work on SSE-only platform, but with limited performance.\n\n# 2. Usage\n\n`kmer-db \u003cmode\u003e [options] \u003cpositional arguments\u003e`\n\nKmer-db operates in one of the following modes:\n\n* `build` - building a database from samples,\n* `all2all` - counting common k-mers - all samples in the database,\n* `all2all-sp` - counting common k-mers - all samples in the database (sparse computation),\n* `all2all-parts` - counting common k-mers - all samples within from databases (sparse computation),\n* `new2all` - counting common k-mers - set of new samples versus database,\n* `one2all` - counting common k-mers - single sample versus database,\n* `distance` - calculating similarities/distances,\n* `minhash` - storing minhashed k-mers.\n    \nCommon options:\n* `-t \u003cthreads\u003e` - number of threads (default: number of available cores),\n    \nThe meaning of other options and positional arguments depends on the selected mode.\n    \n## 2.1. Building a database\n\nConstruction of k-mers database is an obligatory step for further analyses. The procedure accepts several input types:\n* compressed or uncompressed genomes/reads:\n\n    ```kmer-db build [-k \u003ckmer-length\u003e] [-f \u003cfraction\u003e] [-multisample-fasta] [-extend] [-alphabet \u003calphabet\u003e] [-preserve-strand] [-t \u003cthreads\u003e] \u003csamples\u003e \u003cdatabase\u003e```\n* [KMC-generated](https://github.com/refresh-bio/KMC) k-mers: \n\n    ```kmer-db build -from-kmers [-f \u003cfraction\u003e] [-extend] [-t \u003cthreads\u003e] \u003csamples\u003e \u003cdatabase\u003e```\n  \n* [minhashed k-mers](#24-storing-minhashed-k-mers) produced by `minhash` mode:\n\n    ```kmer-db build -from-minhash [-extend] [-t \u003cthreads\u003e] \u003csamples\u003e \u003cdatabase\u003e```\n\nParameters:\n * `samples` (input) - one of the following: \n    * FASTA file (*fa*, *fna*, *fasta*, *fa.gz*, *fna.gz*, *fasta.gz*) with one or multiple (`-multisample-fasta` switch) samples\n    * file with a newline-separated list of samples:\n      ```\n      sample_file_1\n      sample_file_2\n      sample_file_3\n      ...\n      ```\n   Every file can be in one of the formats:\n     1. FASTA genomes/reads (default). If a file on the list cannot be found, the following extensions are tested: *fa*, *fna*, *fasta*, *gz*, *fa.gz*, *fna.gz*, *fasta.gz*.\n     2. [KMC-generated](https://github.com/refresh-bio/KMC) k-mer files (`-from-kmers` switch specified). A set of two KMC files (*.kmc_pre* + *.kmc_suf*) is required for every list entry.\n     3. minhashed k-mers (`-from-minhash` switch specified). Minhashed k-mer files (*.minhash*) must be generated by `minhash` command [prior to the database construction](#24-storing-minhashed-k-mers).  \n\tNote, that minhashing may be also done during the database construction by specyfying `-f` option.\n* `database` (output) - file with generated k-mer database, \n* `-k \u003ckmer-length\u003e` - length of k-mers (default: 18); ignored when `-from-kmers` or `-from-minhash` switch is specified,\n* `-f \u003cfraction\u003e` - fraction of all k-mers to be accepted by the minhash filter during database construction (default: 1); ignored when `-from-minhash` switch is present,\n* `-multisample-fasta` - each sequence in a FASTA file is treated as a separate sample,\n* `-extend` - extend the existing database with new samples,\n* `-alphabet` - alphabet:\n  * `nt` (4 symbol nucleotide with indistinguishable T/U; default) \n  * `aa` (20 symbol amino acid)\n  * `aa12_mmseqs` (amino acid reduced to 12 symbols as in MMseqs: AST,C,DN,EQ,FY,G,H,IV,KR,LM,P,W\n  * `aa11_diamond` (amino acid reduced to 11 symbols as in Diamond: KREDQN,C,G,H,ILV,M,F,Y,W,P,STA\n  * `aa6_dayhoff` (amino acid reduced to 6 symbols as proposed by Dayhoff: STPAG,NDEQ,HRK,MILV,FYW,C\n* `-preserve-strand`- preserve strand instead of taking canonical k-mers (allowed only in `nt` alphabet; default: off)\n* `-t \u003cthreads\u003e` - number of threads (default: number of available cores).\n\n## 2.2. Counting common k-mers \n\n### Samples in the database against each other:\n\nDense computations - recomended when the distance matrix contains few zeros. Output can be stored in the dense or sparse form (`-sparse` switch).\n\n`kmer-db all2all [-buffer \u003csize_mb\u003e] [-t \u003cthreads\u003e] [-sparse [-min [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-max [\u003ccriterion\u003e:]\u003cvalue\u003e]* ] \u003cdatabase\u003e \u003ccommon_table\u003e`\n \nSparse computations - recommended when the distance matrix contains many zeros. Output matrix is always in the sparse form:\n\n`kmer-db all2all-sp [-buffer \u003csize_mb\u003e] [-t \u003cthreads\u003e] [-min [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-max [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-sample-rows [\u003ccriterion\u003e:]\u003ccount\u003e] \u003cdatabase\u003e \u003ccommon_table\u003e`\n\nSparse computations, partial databases - use when the distance matrix contains many zeros and there are multiple partial databases. Output matrix is always in the sparse form:\n\n`kmer-db all2all-parts [-buffer \u003csize_mb\u003e] [-t \u003cthreads\u003e] [-min [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-max [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-sample-rows [\u003ccriterion\u003e:]\u003ccount\u003e] \u003cdb_list\u003e \u003ccommon_table\u003e`\n \nParameters:\n* `database` (input) - k-mer database file created by `build` mode,\n* `db_list` (input) - file containing list of databases files created by `build` mode,\n* `common_table` (output) - file containing table with common k-mer counts,\n* `-buffer \u003csize_mb\u003e` - size of cache buffer in megabytes; use L3 size for Intel CPUs and L2 for AMD for best performance; default: 8,\n* `-t \u003cthreads\u003e` - number of threads (default: number of available cores),\n* `-sparse` - stores output matrix in a sparse form (always on in `all2all-sp` and `all2all-parts` modes),\n* `-min [\u003ccriterion\u003e:]\u003cvalue\u003e` - retains elements with `criterion` greater than or equal to `value` (see details below), \n* `-max [\u003ccriterion\u003e:]\u003cvalue\u003e` - retains elements with `criterion` lower than or equal to `value` (see details below),\n* `-sample-rows [\u003ccriterion\u003e:]\u003ccount\u003e` - retains `count` elements in every row using one of the strategies: (i) random selection (no `criterion`); (ii) the best elements with respect to `criterion`.\n\n`criterion` can be `num-kmers` (number of common k-mers) or one of the distance/similarity measures: `jaccard`, `min`, `max`, `cosine`, `mash`, `ani`, `ani-shorder` (see 2.3 for definitions). No `criterion` indicates `num-kmers` (filtering) or random elements selection (sampling). Multiple filters can be combined. \n\n### New samples against the database:\n\n`kmer-db new2all [-multisample-fasta | -from-kmers | -from-minhash] [-t \u003cthreads\u003e]  [-sparse [-min [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-max [\u003ccriterion\u003e:]\u003cvalue\u003e]* ] \u003cdatabase\u003e \u003csamples\u003e \u003ccommon_table\u003e`\n\nParameters:\n* `database` (input) - k-mer database file created by `build` mode,\n* `samples` (input) - file containing samples in one of the supported formats (see `build` mode); if samples are given as genomes (default) or k-mers (`-from-kmers` switch), the minhashing is done automatically with the same filter as in the database,\n* `common_table` (output) - file containing table with common k-mer counts,\n* `-multisample-fasta` / `-from-kmers` / `-from-minhash` - see `build` mode for details,\n* `-t \u003cthreads\u003e` - number of threads (default: number of available cores),\n* `-sparse` - stores output matrix in a sparse form,\n* `-min [\u003ccriterion\u003e:]\u003cvalue\u003e` - retains elements with `criterion` greater than or equal to `value` (see details below), \n* `-max [\u003ccriterion\u003e:]\u003cvalue\u003e` - retains elements with `criterion` lower than or equal to `value` (see details below),\n\n`criterion` can be `num-kmers` (number of common k-mers) or one of the distance/similarity measures: `jaccard`, `min`, `max`, `cosine`, `mash`, `ani`, `ani-shorder` (see 2.3 for definitions). No `criterion` indicates `num-kmers`. Multiple filters can be combined.\n \n### Single sample against the database:\n\n`kmer-db one2all [-from-kmers | -from-minhash] [-t \u003cthreads\u003e] \u003cdatabase\u003e \u003csample\u003e \u003ccommon_table\u003e`\n\nThe meaning of the parameters is the same as in `new2all` mode, but instead of specifying file with sample list, a single sample file is used as a query.\n\n### Output format\n\nModes `all2all`, `all2all-sp`, `all2all-parts`, `new2all`, and `one2all` produce a comma-separated table with numbers of common k-mers. For `all2all`, `new2all`, and `one2all` modes, the table is by default stored in a dense form:\n\n| \t\t\t\t\t\t\t\t\t| \t\t\t\t\t\t\t\t| \t\t\t\t\t| \t\t\t\t\t|\t\t|\t\t\t|\t\n| :---: \t\t\t\t\t\t\t| :---: \t\t\t\t\t\t| :---: \t\t\t| :---:\t\t\t\t| :---:\t|  :---:\t| \n| kmer-length: *k* fraction: *f* \t| db-samples \t\t\t\t\t| *s\u003csub\u003e1\u003c/sub\u003e*\t\t\t\t\t\t\t\t\t| *s\u003csub\u003e2\u003c/sub\u003e* \t\t\t\t\t\t\t\t\t\t| ... \t|  *s\u003csub\u003en\u003c/sub\u003e* |\n| query-samples \t\t\t\t\t| total-kmers \t\t\t\t\t| \u0026#124;*s\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t\t\t\t\t\t| \u0026#124;*s\u003csub\u003e2\u003c/sub\u003e*\u0026#124; \t\t\t\t\t\t\t| ... \t|  \u0026#124;*s\u003csub\u003en\u003c/sub\u003e*\u0026#124; |\n| *q\u003csub\u003e1\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t| \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e \u0026cap; s\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t| \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e \u0026cap; s\u003csub\u003e2\u003c/sub\u003e*\u0026#124; \t| ... \t|  \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e \u0026cap; s\u003csub\u003en\u003c/sub\u003e*\u0026#124; |\n| *q\u003csub\u003e2\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e*\u0026#124;\t| \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e \u0026cap; s\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t| \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e \u0026cap; s\u003csub\u003e2\u003c/sub\u003e*\u0026#124; \t| ... \t|  \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e \u0026cap; s\u003csub\u003en\u003c/sub\u003e*\u0026#124; |\n| ... \t\t\t\t\t\t\t\t| ...\t\t\t\t\t\t\t| ...\t\t\t\t\t\t\t\t\t\t\t\t| ...\t\t\t\t\t\t\t\t\t\t\t\t\t| ...\t|\t...\t\t\t\t\t\t\t\t\t\t\t\t |\n| *q\u003csub\u003em\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003em\u003c/sub\u003e*\u0026#124;\t| \u0026#124;*q\u003csub\u003em\u003c/sub\u003e \u0026cap; s\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t| \u0026#124;*q\u003csub\u003em\u003c/sub\u003e \u0026cap; s\u003csub\u003e2\u003c/sub\u003e*\u0026#124; \t| ... \t|  \u0026#124;*q\u003csub\u003em\u003c/sub\u003e \u0026cap; s\u003csub\u003en\u003c/sub\u003e*\u0026#124; |\n\nwhere:\n* *k* - k-mer length,\n* *f* - minhash fraction (1, when minhashing is disabled), \n* *s\u003csub\u003e1\u003c/sub\u003e*, *s\u003csub\u003e2\u003c/sub\u003e*,  ...,   *s\u003csub\u003en\u003c/sub\u003e* - database sample names,\n* *q\u003csub\u003e1\u003c/sub\u003e*, *q\u003csub\u003e2\u003c/sub\u003e*,  ...,   *q\u003csub\u003em\u003c/sub\u003e* - query sample names,\n* \u0026#124;*a*\u0026#124; - number of k-mers in sample *a*,\n* \u0026#124;*a \u0026cap; b*\u0026#124; - number of k-mers common for samples *a* and *b*.\n\nWhen `-sparse` switch is specified or `all2all-sp`, `all2all-parts` modes are used, the table is stored in a sparse form. In particular, zeros are omitted while non-zero elements are represented as pairs (*column_id*: *value*) with 1-based column indexing. Thus, rows may have different number of elements, e.g.:\n\n| \t\t\t\t\t\t\t\t\t| \t\t\t\t\t\t\t\t| \t\t\t\t\t| \t\t\t\t|\t\t|\t\t\t|\t\n| :---: \t\t\t\t\t\t\t| :---: \t\t\t\t\t\t| :---: \t\t\t| :---:\t\t\t| :---:\t|  :---:\t| \n| kmer-length: *k* fraction: *f* \t| db-samples \t\t\t\t\t| *s\u003csub\u003e1\u003c/sub\u003e*\t\t\t\t\t| *s\u003csub\u003e2\u003c/sub\u003e* | ... \t|  *s\u003csub\u003en\u003c/sub\u003e* |\n| query-samples \t\t\t\t\t| total-kmers \t\t\t\t\t| \u0026#124;*s\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t\t| \u0026#124;*s\u003csub\u003e2\u003c/sub\u003e*\u0026#124; \t| ... \t|  \u0026#124;*s\u003csub\u003en\u003c/sub\u003e*\u0026#124; |\n| *q\u003csub\u003e1\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e*\u0026#124;\t| *i\u003csub\u003e11\u003c/sub\u003e*: \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e \u0026cap; s\u003csub\u003ei\u003csub\u003e11\u003c/sub\u003e\u003c/sub\u003e*\u0026#124;\t| *i\u003csub\u003e12\u003c/sub\u003e*: \u0026#124;*q\u003csub\u003e1\u003c/sub\u003e \u0026cap; s\u003csub\u003ei\u003csub\u003e12\u003c/sub\u003e\u003c/sub\u003e*\u0026#124; | ||\n| *q\u003csub\u003e2\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e*\u0026#124;\t| *i\u003csub\u003e21\u003c/sub\u003e*: \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e \u0026cap; s\u003csub\u003ei\u003csub\u003e21\u003c/sub\u003e\u003c/sub\u003e*\u0026#124;\t| *i\u003csub\u003e22\u003c/sub\u003e*: \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e \u0026cap; s\u003csub\u003ei\u003csub\u003e22\u003c/sub\u003e\u003c/sub\u003e*\u0026#124; \t| *i\u003csub\u003e23\u003c/sub\u003e*: \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e \u0026cap; s\u003csub\u003ei\u003csub\u003e23\u003c/sub\u003e\u003c/sub\u003e*\u0026#124;  \t| |   \n| *q\u003csub\u003e2\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003e2\u003c/sub\u003e*\u0026#124;\t| ||||\n| ... \t\t\t\t\t\t\t\t| ...\t\t\t\t\t\t\t| ... ||||\n| *q\u003csub\u003em\u003c/sub\u003e* \t\t\t\t\t| \u0026#124;*q\u003csub\u003em\u003c/sub\u003e*\u0026#124;\t| *i\u003csub\u003em1\u003c/sub\u003e*: \u0026#124;*q\u003csub\u003em\u003c/sub\u003e \u0026cap; s\u003csub\u003ei\u003csub\u003em1\u003c/sub\u003e\u003c/sub\u003e*\u0026#124;\t| |||\n\nFor performance reasons, `all2all`, `all2all-sp`, and `all2all-parts` modes produce a lower triangular matrix.\n\n \n ## 2.3. Calculating similarities or distances\n\n`kmer-db distance \u003cmeasure\u003e [-sparse [-min [\u003ccriterion\u003e:]\u003cvalue\u003e]* [-max [\u003ccriterion\u003e:]\u003cvalue\u003e]* ] \u003ccommon_table\u003e \u003coutput_table\u003e`\n\nParameters:\n* `measure` - names of the similarity/distance measure to be calculated, can be one of the following: \n  * `jaccard`: $J(q,s) = |p \\cap q| / |p \\cup q|$, \n  * `min`: $\\min(q,s) =  |p \\cap q| / \\min(|p|,|q|)$, \n  * `max`: $\\max(q,s) =  |p \\cap q| / \\max(|p|,|q|)$, \n  * `cosine`: $\\cos(q,s) = |p \\cap q| / \\sqrt{|p| \\cdot |q|}$,  \n  * `mash` (Mash distance): $\\textrm{Mash}(q,s) = -\\frac{1}{k}ln\\frac{2 \\cdot J(q,s)}{1 + J(q,s)}$, \n  * `ani` (average nucleotide identity): $\\textrm{ANI}(q,s) = 1 - \\textrm{Mash}(p,q)$,\n  * `ani-shorter` - same as `ani` but with `min` used instead of `jaccard`.\n* `common_table` (input) - file containing table with numbers of common k-mers produced by `all2all`, `new2all`, or `one2all` mode (both, dense and sparse matrices are supported), \n* `output_table` (output) - file containing table with calculated distance measure,  \n* `-phylip-out` - store output distance matrix in a Phylip format,\n* `-sparse` - outputs a sparse matrix (only for dense input matrices - sparse inputs always produce sparse outputs),\n* `-min [\u003ccriterion\u003e:]\u003cvalue\u003e` - retains elements with `criterion` greater than or equal to `value` (see details below), \n* `-max [\u003ccriterion\u003e:]\u003cvalue\u003e` - retains elements with `criterion` lower than or equal to `value` (see details below),\n\n`criterion` can be `num-kmers` (number of common k-mers) or one of the distance/similarity measures: `jaccard`, `min`, `max`, `cosine`, `mash`, `ani`, `ani-shorder` (see 2.3 for definitions). If no `criterion` is specified, `measure` argument is used by default. Multiple filters can be combined.\n \n        \n## 2.4. Storing minhashed k-mers\n\nThis is an optional analysis step which stores minhashed k-mers on the hard disk to be later consumed by `build`, `new2all`, or `one2all` modes with `-from-minhash` switch. It can be skipped if one wants to use all k-mers from samples for distance estimation or employs minhashing during database construction. Syntax:\n\n`kmer-db minhash [-f \u003cfraction\u003e] [-k \u003ckmer-length\u003e] [-multisample-fasta] [-alphabet \u003calphabet\u003e] [-preserve-strand] \u003csamples\u003e`\n\n`kmer-db minhash -from-kmers [-f \u003cfraction\u003e] \u003csamples\u003e`\n\nParameters:\n * `sample_list` (input) - file containing list of samples in one of the supported formats (see `build` mode), \n * `-f \u003cfraction\u003e` - fraction of all k-mers to be accepted by the minhash filter (default: 0.01),\n * `-k \u003ckmer-length\u003e` - length of k-mers (default: 18; maximum: 30); ignored when `-from-kmers` switch is specified,\n * `-multisample-fasta` / `-from-kmers` - see `build` mode for details.\n * `-alphabet` - alphabet:\n   * `nt` (4 symbol nucleotide with indistinguishable T/U; default) \n   * `aa` (20 symbol amino acid)\n   * `aa12_mmseqs` (amino acid reduced to 12 symbols as in MMseqs: AST,C,DN,EQ,FY,G,H,IV,KR,LM,P,W\n   * `aa11_diamond` (amino acid reduced to 11 symbols as in Diamond: KREDQN,C,G,H,ILV,M,F,Y,W,P,STA\n   * `aa6_dayhoff` (amino acid reduced to 6 symbols as proposed by Dayhoff: STPAG,NDEQ,HRK,MILV,FYW,C\n* `-preserve-strand`- preserve strand instead of taking canonical k-mers (allowed only in `nt` alphabet; default: off)\n\nFor each sample from the list, a binary file with *.minhash* extension containing filtered k-mers is created.\n\n\n# 3. Datasets\nList of the pathogens investigated in Kmer-db study can be found [here](https://github.com/refresh-bio/kmer-db/tree/master/data)\n\n## Citing\n[Deorowicz, S., Gudyś, A., Długosz, M., Kokot, M., Danek, A. (2019) Kmer-db: instant evolutionary distance estimation, Bioinformatics, 35(1): 133–136](https://academic.oup.com/bioinformatics/advance-article-abstract/doi/10.1093/bioinformatics/bty610/5050791?redirectedFrom=fulltext)\n\n[Zielezinski A, Gudyś A, Barylski J, Siminski K, Rozwalak P, Dutilh BE, Deorowicz S. Ultrafast and accurate sequence alignment and clustering of viral genomes. Nat Methods. https://doi.org/10.1038/s41592-025-02701-7](https://doi.org/10.1038/s41592-025-02701-7)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefresh-bio%2Fkmer-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefresh-bio%2Fkmer-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefresh-bio%2Fkmer-db/lists"}