How sivasubramanics/kcftools works
Project Type & Purpose
• Type: Command‐line bioinformatics tool (no GUI/web frontend).
• Purpose: Identify genomic variations by comparing reference *k*-mers against query k-mer databases (KMC), produce .kcf, TSV, JSON, cohort files, etc.
Top‐Level Components
a. CLI Parser & Dispatcher
– Class: KCFTOOLS.java (main method, argument parsing).
– Uses a “Plugin Manager” (loads/dispatches commands).
b. Plugin Layer (Command Pattern)
– Each plugin implements execute(args) and orchestrates processing steps.
Core Processing Layer
For each plugin, illustrate its internal flow:
– Input Readers
• FASTA reader: Data/Fasta + FastaIndex
• KMC DB reader: Data/KMC
• GTF reader: Data/GTF
• KCF reader: Data/KCFReader (for commands that ingest .kcf)
– Variation Engine (for getVariations & related)
• Windowing logic: Data/Window
• K-mer operations: Data/Kmer, Data/Signature
• Distance & scoring calculations: encapsulated in plugin + helper functions
– Output Writers
• KCF writer: Data/KCFWriter
• TSV/JSON: (Plugins or generic code serializing to TSV/JSON)
– Data Structures
• Data package classes (e.g., Data.java, Signature.java, Window.java) represent in‐memory models.
Utility Services
– Utils/Configs.java (configuration loading)
– Utils/Logger.java (logging)
– Utils/HelperFunctions.java (common routines)
These are injected or called by both the CLI dispatcher and all plugins.
External Dependencies & Resources
– File System
• Reference FASTA files
• GTF annotation files
• Input .kcf files (for some commands)
– KMC Database
• KMC3 on‐disk DB files (<prefix>.kmc_pre, etc.)
– Third‐party Tools/Frameworks
• Java 17+ runtime
• Maven build system
• Logging framework (if external)
– Script Utilities (in utils/ folder)
• Shell wrapper: run_kcftools.sh
• Plot scripts: plotIBS.R, plotVariationHistogram.py, etc.
These are “outside” your core application but important for workflows.
Relationships & Data Flow
• Sequence:
1. User runs kcftools getVariations …
2. CLI Parser instantiates GetVariations plugin
3. Plugin reads FASTA & KMC DB
4. Plugin loops windows, queries k-mers, computes scores
5. Plugin streams results to KCFWriter
6. Resulting .kcf file on disk
Architectural Patterns & Design Principles
• Command Pattern: each subcommand is its own plugin class.
• Layered Architecture:
– CLI Layer
– Orchestration/Plugin Layer
– Core Logic Layer (Data models + algorithms)
– I/O Layer (file readers/writers)
– Utility Layer (common services)
• Separation of Concerns: I/O separated from computation, configuration separate from code, logging centralized.