KMC utilities

ASOkai provides Python wrappers around the external kmc and kmc_tools executables. Install ASOkai through the supplied Conda environment when using these utilities so that both binaries are available on PATH.

Warning

KMC is third-party GPLv3-only software. ASOkai invokes its executables but does not distribute or link against KMC. See the third-party software section of the project README for licensing details.

Imports

from ASOkai.Utils import KMC, KMCTools

Running KMC

KMC accepts the executable name or an explicit executable path. Its run method follows the KMC command-line interface and returns a completed subprocess result.

KMC().run(
    "reads.fastq",
    "counts/sample",
    "work",
    k=25,
    t=8,
)

Input paths are resolved to absolute paths. Prefix a list file with @ as required by KMC. Set check=True to raise KMCExecutionError when the process exits unsuccessfully. For KFF output, a path ending in .kff is treated as the final filename; KMC receives the corresponding suffix-free prefix so that it does not produce .kff.kff.

Pipeline integration

The built-in build-kmc-index step creates one durable KFF index from a supplied plain or gzip-compressed FASTA. Link its reference input to the dna output of a named download-genome run, or supply an existing FASTA path. Analyses can reuse the index and batch their query k-mers; short query passes do not need separate persistent pipeline steps.

The index builder converts resources.build-kmc-index.memory_mb (or the default memory resource) to KMC’s integer -m setting by dividing by 1024 and rounding down. ASOkai requires at least 2048 MiB for this step. The step accepts --param overrides for FASTA format, strict-memory and homopolymer modes, signature length, count thresholds, canonicalization, RAM-only mode, bin count, per-stage thread counts, and output-size optimization. Set parameters.kmc.sm to true if KMC must enforce its memory limit strictly. These options also have optional parameters.kmc configuration keys. The output filename includes only options that affect input interpretation, retained counts, or KFF representation, as key/value segments such as .k16.ffm.ci1.. The directory uses the configured genome assembly, source, and Ensembl release. These values are required when planning the builder; the step does not infer them from the FASTA. KFF output is fixed for this step; KMC modes that suppress the index are not available here.

Running kmc_tools

KMCTools exposes the Simple, Transform, Filter, and Complex wrappers. Each builder records an operation and executes it when run is called.

KMCTools.Transform().reduce(
    "valid-kmers",
    ci=2,
).dump(
    "valid-kmers.txt",
).run(
    "counts/sample",
    t=8,
)

All wrappers accept kmc_tools from PATH by default or an explicit executable path. Shared execution options include t, v, hp, debug, check, and cwd. Operation-specific options follow the upstream kmc_tools command-line interface. When check=True, an unsuccessful process raises KMCTools.KMCToolsExecutionError.

KMC API

class ASOkai.Utils.KMC(kmc_executable='kmc')[source]

Bases: object

Runs the kmc executable. Options mirror KMC 3.2.x CLI.

Parameters:

kmc_executable (str)

property executable: str
run(input_path, output_db_prefix, working_directory, *, k=25, m=12, f='fm', t=None, sm=False, hc=False, p=None, ci=None, cs=None, cx=None, b=False, r=False, n=None, sf=None, sp=None, sr=None, j=None, w=False, o=None, hp=False, e=False, opt_out_size=False, v=False, debug=True, check=True, additional_args=None)[source]

Execute kmc with the provided parameters.

output_db_prefix retains KMC’s native prefix behavior, except that a .kff suffix with o="kff" is treated as the final filename.

Parameters:

  • input_path (str | Path)

  • output_db_prefix (str | Path)

  • working_directory (str | Path)

  • k (int)

  • m (int)

  • f (Literal['fa', 'fq', 'fm', 'fbam', 'fkmc'])

  • t (int | None)

  • sm (bool)

  • hc (bool)

  • p (int | None)

  • ci (int | None)

  • cs (int | None)

  • cx (int | None)

  • b (bool)

  • r (bool)

  • n (int | None)

  • sf (int | None)

  • sp (int | None)

  • sr (int | None)

  • j (str | Path | None)

  • w (bool)

  • o (Literal['kmc', 'kff'] | None)

  • hp (bool)

  • e (bool)

  • opt_out_size (bool)

  • v (bool)

  • debug (bool)

  • check (bool)

  • additional_args (Sequence[str] | None)

Return type:

CompletedProcess[str]

exception ASOkai.Utils.KMCExecutionError(message, *, returncode, cmd, stdout=None, stderr=None)[source]

Bases: RuntimeError

Raised when kmc exits with a non-zero status (when check is True).

Parameters:

  • message (str)

  • returncode (int)

  • cmd (list[str])

  • stdout (str | None)

  • stderr (str | None)

Return type:

None

kmc_tools API

class ASOkai.Utils.KMCTools.Simple(kmc_tools_executable='kmc_tools')[source]

Bases: KMCTool

Parameters:

kmc_tools_executable (str)

intersect(output, **kwargs)[source]
Parameters:

  • output (str | Path)

  • kwargs (Any)

Return type:

Simple

union(output, **kwargs)[source]
Parameters:

  • output (str | Path)

  • kwargs (Any)

Return type:

Simple

kmers_subtract(output, **kwargs)[source]
Parameters:

  • output (str | Path)

  • kwargs (Any)

Return type:

Simple

counters_subtract(output, **kwargs)[source]
Parameters:

  • output (str | Path)

  • kwargs (Any)

Return type:

Simple

reverse_kmers_subtract(output, **kwargs)[source]
Parameters:

  • output (str | Path)

  • kwargs (Any)

Return type:

Simple

reverse_counters_subtract(output, **kwargs)[source]
Parameters:

  • output (str | Path)

  • kwargs (Any)

Return type:

Simple

run(input1_path, input2_path, *, input1_ci=None, input1_cx=None, input2_ci=None, input2_cx=None, t=None, v=False, hp=False, debug=True, check=True, cwd=None)[source]
Parameters:

  • input1_path (str | Path)

  • input2_path (str | Path)

  • input1_ci (int | None)

  • input1_cx (int | None)

  • input2_ci (int | None)

  • input2_cx (int | None)

  • t (int | None)

  • v (bool)

  • hp (bool)

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

class ASOkai.Utils.KMCTools.Transform(kmc_tools_executable='kmc_tools')[source]

Bases: KMCTool

Parameters:

kmc_tools_executable (str)

sort(output=None, *, ci=None, cx=None, cs=None, o=None)[source]
Parameters:

  • output (str | Path | None)

  • ci (int | None)

  • cx (int | None)

  • cs (int | None)

  • o (Literal['kmc', 'kff'] | None)

Return type:

Transform

reduce(output=None, *, ci=None, cx=None, cs=None, o=None)[source]
Parameters:

  • output (str | Path | None)

  • ci (int | None)

  • cx (int | None)

  • cs (int | None)

  • o (Literal['kmc', 'kff'] | None)

Return type:

Transform

compact(output=None, *, o=None)[source]
Parameters:

  • output (str | Path | None)

  • o (Literal['kmc', 'kff'] | None)

Return type:

Transform

histogram(output=None, *, ci=None, cx=None)[source]
Parameters:

  • output (str | Path | None)

  • ci (int | None)

  • cx (int | None)

Return type:

Transform

dump(output=None, *, s=False)[source]
Parameters:

  • output (str | Path | None)

  • s (bool)

Return type:

Transform

set_counts(value, output=None, *, o=None)[source]
Parameters:

  • value (int)

  • output (str | Path | None)

  • o (Literal['kmc', 'kff'] | None)

Return type:

Transform

run(input_path, *, ci=None, cx=None, t=None, v=False, hp=False, debug=True, check=True, cwd=None)[source]
Parameters:

  • input_path (str | Path)

  • ci (int | None)

  • cx (int | None)

  • t (int | None)

  • v (bool)

  • hp (bool)

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

class ASOkai.Utils.KMCTools.Filter(kmc_tools_executable='kmc_tools')[source]

Bases: KMCTool

Parameters:

kmc_tools_executable (str)

run(kmc_input_db_path, input_read_set_path, output_read_set_path, *, trim=False, hm=False, db_ci=None, db_cx=None, read_ci=None, read_cx=None, read_f=None, output_f=None, t=None, v=False, hp=False, debug=True, check=True, cwd=None)[source]
Parameters:

  • kmc_input_db_path (str | Path)

  • input_read_set_path (str | Path)

  • output_read_set_path (str | Path)

  • trim (bool)

  • hm (bool)

  • db_ci (int | None)

  • db_cx (int | None)

  • read_ci (int | float | None)

  • read_cx (int | float | None)

  • read_f (Literal['a', 'q'] | None)

  • output_f (Literal['a', 'q'] | None)

  • t (int | None)

  • v (bool)

  • hp (bool)

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

class ASOkai.Utils.KMCTools.Complex(kmc_tools_executable='kmc_tools')[source]

Bases: KMCTool

Parameters:

kmc_tools_executable (str)

run(operations_definition_file, *, t=None, v=False, hp=False, debug=True, check=True, cwd=None)[source]
Parameters:

  • operations_definition_file (str | Path)

  • t (int | None)

  • v (bool)

  • hp (bool)

  • debug (bool)

  • check (bool)

  • cwd (str | Path | None)

Return type:

CompletedProcess[str]

exception ASOkai.Utils.KMCTools.KMCToolsExecutionError(message, *, returncode, cmd, stdout=None, stderr=None)[source]

Bases: RuntimeError

Parameters:

  • message (str)

  • returncode (int)

  • cmd (list[str])

  • stdout (str | None)

  • stderr (str | None)

Return type:

None