Build KMC index

Builds a reusable KMC KFF index from a FASTA reference.

Step type:: Utility step

Run this step

ASOkai run --step build-kmc-index --config-file ./config.yaml

Example configuration for this step:

datadir: ./data
parameters:
  target:
    k: 16

Parameters

These scalar configuration values are passed to this step.

Configuration path	Details
`parameters.target.k`	Accepted value: integer; minimum: 1 Requirement: Required Description: Target-site length.
`parameters.kmc.f`	Accepted value: string; one of: fa, fm Requirement: Optional Description: FASTA input format.
`parameters.kmc.sm`	Accepted value: boolean Requirement: Optional Description: Use strict memory mode.
`parameters.kmc.hc`	Accepted value: boolean Requirement: Optional Description: Count homopolymer-compressed k-mers.
`parameters.kmc.p`	Accepted value: integer or null; minimum: 5; maximum: 11 Requirement: Optional Description: Signature length.
`parameters.kmc.ci`	Accepted value: integer; minimum: 1 Requirement: Optional Description: Minimum count to retain.
`parameters.kmc.cs`	Accepted value: integer or null; minimum: 1 Requirement: Optional Description: Maximum stored count.
`parameters.kmc.cx`	Accepted value: integer or null; minimum: 1 Requirement: Optional Description: Maximum count to retain.
`parameters.kmc.b`	Accepted value: boolean Requirement: Optional Description: Disable canonical k-mers.
`parameters.kmc.r`	Accepted value: boolean Requirement: Optional Description: Use RAM-only mode.
`parameters.kmc.n`	Accepted value: integer or null; minimum: 1 Requirement: Optional Description: Number of bins.
`parameters.kmc.sf`	Accepted value: integer or null; minimum: 1 Requirement: Optional Description: Input-reading threads.
`parameters.kmc.sp`	Accepted value: integer or null; minimum: 1 Requirement: Optional Description: Splitting threads.
`parameters.kmc.sr`	Accepted value: integer or null; minimum: 1 Requirement: Optional Description: Second-stage threads.
`parameters.kmc.opt_out_size`	Accepted value: boolean Requirement: Optional Description: Optimize output database size.

Parameter rules

exactly one of these config values is required: target_id, target_name

Inputs

An input with a fixed producer uses that output by default. A selected run can instead link a named output or supply an existing path. The input’s path override in config.yaml also selects an existing file. External paths are validated against the input’s file contract.

File input	Details
`reference`	Shared config source: `steps.build-kmc-index.inputs.reference.path` or `steps.build-kmc-index.inputs.reference.from` Format: plain or gzip-compressed FASTA reference Description: Plain or gzip-compressed FASTA reference to count.

Example path-override configuration:

steps:
  build-kmc-index:
    inputs:
      reference:
        path: /path/to/reference.fa

Resources

Configurable resources use the first value in the resolution order shown below.

Resource setting	Details
`n_workers`	Step override: `resources.build-kmc-index.n_workers` Shared default: `resources.default.n_workers` Built-in fallback: 1 Accepted value: integer; minimum: 1 Description: Number of workers allocated to a step that supports parallel execution.
`memory_mb`	Step override: `resources.build-kmc-index.memory_mb` Shared default: `resources.default.memory_mb` Built-in fallback: 4096 Accepted value: integer; minimum: 1 Description: Memory in mebibytes allocated to this step.

Outputs

File output paths are relative to datadir. Braced names are replaced with the corresponding parameter values.

File outputs

File output	Details
`kmc_index`	Format: KFF k-mer index Description: Reference k-mer counts in KFF format. Path template: `{assembly}/{source}/{release}/indexes/kmc/index.k{k}.f{f}.hc{hc}.ci{ci}.cs{cs}.cx{cx}.b{b}.opt_out_size{opt_out_size}.kff` Example path: `GRCh38/ensembl/114/indexes/kmc/index.k16.ffm.hcFalse.ci1.csna.cxna.bFalse.opt_out_sizeFalse.kff`

Note

This step invokes the third-party kmc and kmc_tools executables. KMC is GPLv3-only software; ASOkai does not distribute or link against it. Install the executables through the supplied Conda environment.

Supply a plain or gzip-compressed FASTA file as reference. The step builds one KFF index using the configured k-mer length and KMC options. Set resources.build-kmc-index.memory_mb to control KMC’s memory limit. Configure parameters.genome.assembly, parameters.genome.source, and parameters.genome.release to place the index under its genome directory. Link the step to a named genome download when the FASTA needs to be created:

datadir: /path/to/data
parameters:
  genome:
    assembly: GRCh38
    source: ensembl
    release: 114
    species: Homo_sapiens
runs:
  - step: download-genome
    id: genome
  - step: build-kmc-index
    parameters:
      k: 16
    inputs:
      reference:
        from: run.genome.dna

If the FASTA already exists, select only build-kmc-index and supply its reference input with {path: /path/to/genome.fa}. For a target gene, name an instantiate-target-gene task run target_gene and link reference to run.target_gene.fasta instead.