rustkmer 0.5.2

High-performance k-mer counting tool in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224

//! Text output format for k-mer counts
//!
//! Provides human-readable text format for k-mer counting results.

use crate::error::{ProcessingError, ProcessingResult};
use crate::hash::table::CounterStats;
use crate::kmer::encoding::decode_kmer;
use std::io::Write;

/// Write k-mer counts in text format
///
/// Each line contains: `kmer_sequence<TAB>count`
///
/// # Arguments
/// * `writer` - Output writer
/// * `kmer_counts` - Vector of (kmer, count) pairs
/// * `kmer_length` - Length of k-mers
/// * `include_header` - Whether to include header information
///
/// # Returns
/// Result indicating success or error
pub fn write_text_format<W: Write>(
    mut writer: W,
    kmer_counts: &[(u64, u32)],
    kmer_length: usize,
    include_header: bool,
) -> ProcessingResult<()> {
    // Write header if requested
    if include_header {
        writeln!(writer, "# rustkmer text format v1")
            .map_err(|e| ProcessingError::with_context("Failed to write header", e))?;
        writeln!(writer, "# kmer_length: {}", kmer_length)
            .map_err(|e| ProcessingError::with_context("Failed to write kmer length", e))?;
        writeln!(writer, "# total_kmers: {}", kmer_counts.len())
            .map_err(|e| ProcessingError::with_context("Failed to write total k-mers", e))?;
        writeln!(writer, "# format: kmer_sequence<TAB>count")
            .map_err(|e| ProcessingError::with_context("Failed to write format description", e))?;
    }

    // Write k-mer counts
    for (kmer, count) in kmer_counts {
        let sequence = decode_kmer(*kmer, kmer_length);
        writeln!(writer, "{}\t{}", sequence, count)
            .map_err(|e| ProcessingError::with_context("Failed to write k-mer count", e))?;
    }

    Ok(())
}

/// Write k-mer counts in JSON format
///
/// # Arguments
/// * `writer` - Output writer
/// * `kmer_counts` - Vector of (kmer, count) pairs
/// * `kmer_length` - Length of k-mers
/// * `stats` - Statistics for metadata
///
/// # Returns
/// Result indicating success or error
pub fn write_json_format<W: Write>(
    mut writer: W,
    kmer_counts: &[(u64, u32)],
    kmer_length: usize,
    stats: &CounterStats,
) -> ProcessingResult<()> {
    writeln!(writer, "{{")
        .map_err(|e| ProcessingError::with_context("Failed to write JSON start", e))?;
    writeln!(writer, "  \"format\": \"rustkmer-json\",")
        .map_err(|e| ProcessingError::with_context("Failed to write format", e))?;
    writeln!(writer, "  \"version\": 1,")
        .map_err(|e| ProcessingError::with_context("Failed to write version", e))?;
    writeln!(writer, "  \"kmer_length\": {},", kmer_length)
        .map_err(|e| ProcessingError::with_context("Failed to write kmer length", e))?;
    writeln!(writer, "  \"canonical_mode\": {},", stats.canonical_mode)
        .map_err(|e| ProcessingError::with_context("Failed to write canonical mode", e))?;
    writeln!(
        writer,
        "  \"total_kmers_processed\": {},",
        stats.total_kmers
    )
    .map_err(|e| ProcessingError::with_context("Failed to write total processed", e))?;
    writeln!(writer, "  \"unique_kmers\": {},", stats.unique_kmers)
        .map_err(|e| ProcessingError::with_context("Failed to write unique count", e))?;
    writeln!(writer, "  \"kmers\": [")
        .map_err(|e| ProcessingError::with_context("Failed to write k-mers start", e))?;

    // Write k-mer counts
    for (i, (kmer, count)) in kmer_counts.iter().enumerate() {
        let sequence = decode_kmer(*kmer, kmer_length);
        let is_last = i == kmer_counts.len() - 1;

        if is_last {
            writeln!(
                writer,
                "    {{\"sequence\": \"{}\", \"count\": {}}}",
                sequence, count
            )
            .map_err(|e| ProcessingError::with_context("Failed to write last k-mer", e))?;
        } else {
            writeln!(
                writer,
                "    {{\"sequence\": \"{}\", \"count\": {}}},",
                sequence, count
            )
            .map_err(|e| ProcessingError::with_context("Failed to write k-mer", e))?;
        }
    }

    writeln!(writer, "  ]")
        .map_err(|e| ProcessingError::with_context("Failed to write k-mers end", e))?;
    writeln!(writer, "}}")
        .map_err(|e| ProcessingError::with_context("Failed to write JSON end", e))?;

    Ok(())
}

/// Write summary statistics only
///
/// # Arguments
/// * `writer` - Output writer
/// * `stats` - Statistics to write
///
/// # Returns
/// Result indicating success or error
pub fn write_summary<W: Write>(mut writer: W, stats: &CounterStats) -> ProcessingResult<()> {
    writeln!(writer, "rustkmer summary:")
        .map_err(|e| ProcessingError::with_context("Failed to write summary header", e))?;
    writeln!(writer, "  K-mer length: {}", stats.kmer_length)
        .map_err(|e| ProcessingError::with_context("Failed to write kmer length", e))?;
    writeln!(writer, "  Canonical mode: {}", stats.canonical_mode)
        .map_err(|e| ProcessingError::with_context("Failed to write canonical mode", e))?;
    writeln!(writer, "  Total k-mers processed: {}", stats.total_kmers)
        .map_err(|e| ProcessingError::with_context("Failed to write total processed", e))?;
    writeln!(writer, "  Unique k-mers: {}", stats.unique_kmers)
        .map_err(|e| ProcessingError::with_context("Failed to write unique count", e))?;

    if stats.total_kmers > 0 {
        let avg_count = stats.total_kmers as f64 / stats.unique_kmers as f64;
        writeln!(writer, "  Average count per k-mer: {:.2}", avg_count)
            .map_err(|e| ProcessingError::with_context("Failed to write average count", e))?;
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::hash::table::CounterStats;

    #[test]
    fn test_text_format() {
        let kmer_counts = vec![(0x12345678, 10), (0x87654321, 5)];
        let mut output = Vec::new();

        write_text_format(&mut output, &kmer_counts, 8, false).unwrap();

        let result = String::from_utf8(output).unwrap();
        let lines: Vec<&str> = result.lines().collect();

        assert_eq!(lines.len(), 2);
        // Each line should have format: sequence<TAB>count
        assert!(lines[0].contains('\t'));
        assert!(lines[1].contains('\t'));
    }

    #[test]
    fn test_text_format_with_header() {
        let kmer_counts = vec![(0x12345678, 10)];
        let mut output = Vec::new();

        write_text_format(&mut output, &kmer_counts, 8, true).unwrap();

        let result = String::from_utf8(output).unwrap();
        let lines: Vec<&str> = result.lines().collect();

        // Should have header lines plus data
        assert!(lines.len() > 1);
        assert!(lines[0].starts_with("# rustkmer"));
        assert!(lines[1].contains("kmer_length"));
    }

    #[test]
    fn test_summary() {
        let stats = CounterStats {
            total_kmers: 1000,
            unique_kmers: 100,
            kmer_length: 21,
            canonical_mode: true,
        };

        let mut output = Vec::new();
        write_summary(&mut output, &stats).unwrap();

        let result = String::from_utf8(output).unwrap();
        assert!(result.contains("K-mer length: 21"));
        assert!(result.contains("Total k-mers processed: 1000"));
        assert!(result.contains("Unique k-mers: 100"));
        assert!(result.contains("Canonical mode: true"));
        assert!(result.contains("Average count per k-mer: 10.00"));
    }

    #[test]
    fn test_json_format() {
        let kmer_counts = vec![(0x12345678, 10)];
        let stats = CounterStats {
            total_kmers: 100,
            unique_kmers: 50,
            kmer_length: 13,
            canonical_mode: false,
        };

        let mut output = Vec::new();
        write_json_format(&mut output, &kmer_counts, 13, &stats).unwrap();

        let result = String::from_utf8(output).unwrap();
        assert!(result.contains("\"format\": \"rustkmer-json\""));
        assert!(result.contains("\"kmer_length\": 13"));
        assert!(result.contains("\"canonical_mode\": false"));
        assert!(result.contains("\"total_kmers_processed\": 100"));
        assert!(result.contains("\"unique_kmers\": 50"));
        assert!(result.contains("\"kmers\": ["));
    }
}