feat: various minor code optimizations

* replace ahash with rustc-hash.  rustc-hash was faster than
  ahash and fxhash empirically.
* fix the usage for threads, where it incorrectly said the minimum
  number of threads was three, and should be five.  This also
  changes the README.

Author: nh13

Cargo.lock

@@ -30,7 +30,6 @@ path = "src/bin/main.rs"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-ahash = "0.8.2"
 anyhow = "1.0.38"
 bstr = "1.0.1"
 clap = { version = "4.0.25", features = ["derive"] }
@@ -49,6 +48,7 @@ serde-aux = "4.1.2"
 seq_io = "0.3.1"
 thiserror = "1.0.37"
 proglog = {version = "0.3.0", features = ["pretty_counts"] }
+rustc-hash = "2.1.1"
 
 [dev-dependencies]
 csv = "1.1.6"

Cargo.toml

@@ -62,13 +62,13 @@ be concatenated using the `-` delimiter and placed in the given SAM record tag (
 default).  Similarly, the sample barcode bases from the given read will be placed in the `BC`
 tag.
 
-Metadata about the samples should be given as a headered metadata TSV file with at least the 
+Metadata about the samples should be given as a headered metadata TSV file with at least the
 following two columns present:
 
-1. `sample_id` - the id of the sample or library. 
+1. `sample_id` - the id of the sample or library.
 2. `barcode` - the expected barcode sequence associated with the `sample_id`.
 
-For reads containing multiple barcodes (such as dual-indexed reads), all barcodes should be 
+For reads containing multiple barcodes (such as dual-indexed reads), all barcodes should be
 concatenated together in the order they are read and stored in the `barcode` field.
 
 The read structures will be used to extract the observed sample barcode, template bases, and
@@ -80,6 +80,7 @@ An observed barcode matches an expected barcode if all the following are true:
    mismatches (see `--max-mismatches`).
 2. The difference between number of mismatches in the best and second best barcodes is greater
    than or equal to the minimum mismatch delta (`--min-mismatch-delta`).
+
 The expected barcode sequence may contains Ns, which are not counted as mismatches regardless
 of the observed base (e.g. the expected barcode `AAN` will have zero mismatches relative to
 both the observed barcodes `AAA` and `AAN`).
@@ -154,7 +155,7 @@ Options:
           [default: 2]
 
   -t, --threads <THREADS>
-          The number of threads to use. Cannot be less than 3
+          The number of threads to use. Cannot be less than 5
 
           [default: 8]
 

README.md

@@ -1,3 +1,3 @@
 [toolchain]
-channel = "1.65.0"
+channel = "1.85.0"
 components = ["rustfmt", "clippy"]

rust-toolchain.toml

@@ -93,6 +93,7 @@ impl ReadSet {
     const SPACE: u8 = b' ';
     const COLON: u8 = b':';
     const PLUS: u8 = b'+';
+    const READ_NUMBERS: &[u8] = b"12345678";
 
     /// Produces an iterator over references to the template segments stored in this ``ReadSet``.
     fn template_segments(&self) -> SegmentIter {
@@ -213,7 +214,12 @@ impl ReadSet {
             None => {
                 // If no pre-existing comment, assume the read is a passing filter, non-control
                 // read and generate a comment for it (sample barcode is added below).
-                write!(writer, "{}:N:0:", read_num)?;
+                if read_num < Self::READ_NUMBERS.len() {
+                    writer.write_all(&[Self::READ_NUMBERS[read_num - 1]])?;
+                    write!(writer, ":N:0:")?;
+                } else {
+                    write!(writer, "{}:N:0:", read_num)?;
+                }
             }
             Some(chars) => {
                 // Else check it's a 4-part name... fix the read number at the front and
@@ -239,7 +245,11 @@ impl ReadSet {
                         &chars[first_colon_idx + 1..chars.len()]
                     };
 
-                    write!(writer, "{}:", read_num)?;
+                    if read_num < Self::READ_NUMBERS.len() {
+                        writer.write_all(&[Self::READ_NUMBERS[read_num - 1], b':'])?;
+                    } else {
+                        write!(writer, "{}:", read_num)?;
+                    }
                     writer.write_all(remainder)?;
 
                     if *remainder.last().unwrap() != Self::COLON {
@@ -518,13 +528,13 @@ impl DemuxMetric {
 /// default).  Similarly, the sample barcode bases from the given read will be placed in the `BC`
 /// tag.
 ///
-/// Metadata about the samples should be given as a headered metadata TSV file with at least the 
+/// Metadata about the samples should be given as a headered metadata TSV file with at least the
 /// following two columns present:
-/// 
-/// 1. `sample_id` - the id of the sample or library. 
+///
+/// 1. `sample_id` - the id of the sample or library.
 /// 2. `barcode` - the expected barcode sequence associated with the `sample_id`.
-/// 
-/// For reads containing multiple barcodes (such as dual-indexed reads), all barcodes should be 
+///
+/// For reads containing multiple barcodes (such as dual-indexed reads), all barcodes should be
 /// concatenated together in the order they are read and stored in the `barcode` field.
 ///
 /// The read structures will be used to extract the observed sample barcode, template bases, and
@@ -536,6 +546,7 @@ impl DemuxMetric {
 ///    mismatches (see `--max-mismatches`).
 /// 2. The difference between number of mismatches in the best and second best barcodes is greater
 ///    than or equal to the minimum mismatch delta (`--min-mismatch-delta`).
+///
 /// The expected barcode sequence may contains Ns, which are not counted as mismatches regardless
 /// of the observed base (e.g. the expected barcode `AAN` will have zero mismatches relative to
 /// both the observed barcodes `AAA` and `AAN`).
@@ -612,7 +623,7 @@ pub(crate) struct Demux {
     #[clap(long, short = 'd', default_value = "2")]
     min_mismatch_delta: usize,
 
-    /// The number of threads to use. Cannot be less than 3.
+    /// The number of threads to use. Cannot be less than 5.
     #[clap(long, short = 't', default_value = "8")]
     threads: usize,
 
@@ -659,9 +670,12 @@ impl Demux {
                 read_structures.iter().map(|s| s.segments_by_type(*output_type).count()).sum();
 
             for idx in 1..=segment_count {
-                output_type_writers.push(BufWriter::new(File::create(
-                    output_dir.join(format!("{}.{}{}.fq.gz", prefix, file_type_code, idx)),
-                )?));
+                output_type_writers.push(BufWriter::with_capacity(
+                    65_536usize,
+                    File::create(
+                        output_dir.join(format!("{}.{}{}.fq.gz", prefix, file_type_code, idx)),
+                    )?,
+                ));
             }
 
             match output_type {
@@ -741,7 +755,7 @@ impl Demux {
             let mut new_sample_barcode_writers = None;
             let mut new_molecular_barcode_writers = None;
 
-            for (optional_ws, target) in vec![
+            for (optional_ws, target) in [
                 (template_writers, &mut new_template_writers),
                 (barcode_writers, &mut new_sample_barcode_writers),
                 (mol_writers, &mut new_molecular_barcode_writers),
@@ -894,7 +908,7 @@ impl Command for Demux {
         );
 
         let mut fq_iterators = fq_sources
-            .zip(self.read_structures.clone().into_iter())
+            .zip(self.read_structures.clone())
             .map(|(source, read_structure)| {
                 ReadSetIterator::new(read_structure, source, self.skip_reasons.clone())
                     .read_ahead(1000, 1000)
@@ -1181,6 +1195,7 @@ mod tests {
             skip_reasons: vec![],
         };
         let demux_result = demux_inputs.execute();
+        #[allow(clippy::permissions_set_readonly_false)]
         permissions.set_readonly(false);
         fs::set_permissions(tmp.path(), permissions).unwrap();
         demux_result.unwrap();
@@ -1875,11 +1890,11 @@ mod tests {
         let read_structures =
             vec![ReadStructure::from_str("+T").unwrap(), ReadStructure::from_str("7B").unwrap()];
 
-        let records = vec![
+        let records = [
             vec!["AAAAAAA", &SAMPLE1_BARCODE[0..7]], // barcode too short
             vec!["CCCCCCC", SAMPLE1_BARCODE],        // barcode the correct length
             vec!["", SAMPLE1_BARCODE],               // template basese too short
-            vec!["G", SAMPLE1_BARCODE],              // barcode the correct length
+            vec!["G", SAMPLE1_BARCODE],
         ];
 
         let input_files = vec![
@@ -1911,11 +1926,11 @@ mod tests {
         let read_structures =
             vec![ReadStructure::from_str("+T").unwrap(), ReadStructure::from_str("7B").unwrap()];
 
-        let records = vec![
+        let records = [
             vec!["AAAAAAA", &SAMPLE1_BARCODE[0..7]], // barcode too short
             vec!["CCCCCCC", SAMPLE1_BARCODE],        // barcode the correct length
             vec!["", SAMPLE1_BARCODE],               // template basese too short
-            vec!["G", SAMPLE1_BARCODE],              // barcode the correct length
+            vec!["G", SAMPLE1_BARCODE],
         ];
 
         let input_files = vec![

src/bin/commands/demux.rs

@@ -1,9 +1,6 @@
 use super::byte_is_nocall;
 use super::samples::Sample;
-use ahash::HashMap as AHashMap;
-use ahash::HashMapExt;
-
-const STARTING_CACHE_SIZE: usize = 1_000_000;
+use rustc_hash::FxHashMap;
 
 /// The struct that contains the info related to the best and next best sample barcode match.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
@@ -33,7 +30,7 @@ pub struct BarcodeMatcher {
     /// If true will attempt to use the cache when matching.
     use_cache: bool,
     /// Caching struct for storing results of previous matches
-    cache: AHashMap<Vec<u8>, BarcodeMatch>,
+    cache: FxHashMap<Vec<u8>, BarcodeMatch>,
 }
 
 impl BarcodeMatcher {
@@ -60,7 +57,7 @@ impl BarcodeMatcher {
         let mut modified_samples = samples.to_vec();
         for sample in modified_samples.iter_mut() {
             sample.barcode = sample.barcode.to_ascii_uppercase();
-            let num_ns = sample.barcode.as_bytes().iter().filter(|&b| byte_is_nocall(*b)).count();
+            let num_ns = sample.barcode_bytes.iter().filter(|&b| byte_is_nocall(*b)).count();
             max_ns_in_barcodes = max_ns_in_barcodes.max(num_ns);
         }
         Self {
@@ -69,28 +66,29 @@ impl BarcodeMatcher {
             max_mismatches,
             min_mismatch_delta,
             use_cache,
-            cache: AHashMap::with_capacity(STARTING_CACHE_SIZE),
+            cache: FxHashMap::default(),
         }
     }
 
     /// Counts the number of bases that differ between two byte arrays.
     fn count_mismatches(observed_bases: &[u8], sample: &Sample) -> u8 {
-        let expected_bases = sample.barcode.as_bytes();
-        let observed_string =
-            std::str::from_utf8(observed_bases).expect("Observed bases are not valid UTF-8");
-        assert_eq!(
-            observed_bases.len(),
-            expected_bases.len(),
-            "Read barcode ({}) length ({}) differs from expected barcode ({}) length ({}) for sample {}",
-            observed_string,
-            observed_bases.len(),
-            sample.barcode,
-            expected_bases.len(),
-            sample.sample_id
-        );
+        if sample.barcode_bytes.len() != observed_bases.len() {
+            let observed_string =
+                std::str::from_utf8(observed_bases).expect("Observed bases are not valid UTF-8");
+            panic!(
+                "Read barcode ({}) length ({}) differs from expected barcode ({}) length ({}) for sample {}",
+                observed_string,
+                observed_bases.len(),
+                sample.barcode,
+                sample.barcode_bytes.len(),
+                sample.sample_id
+            );
+        }
         let mut count: usize = 0;
-        for (&expected_base, &observed_base) in expected_bases.iter().zip(observed_bases.iter()) {
-            if !byte_is_nocall(expected_base) && expected_base != observed_base {
+        for (&expected_base, &observed_base) in
+            sample.barcode_bytes.iter().zip(observed_bases.iter())
+        {
+            if expected_base != observed_base && !byte_is_nocall(expected_base) {
                 count += 1;
             }
         }

src/lib/barcode_matching.rs

@@ -18,6 +18,9 @@ pub struct Sample {
     pub sample_id: String,
     /// DNA barcode associated with the sample
     pub barcode: String,
+    /// DNA barcode as a byte
+    #[serde(skip_deserializing)]
+    pub barcode_bytes: Vec<u8>,
     /// index of the sample in the [`SampleGroup`] object, used for syncing indices across
     /// different structs
     #[serde(skip_deserializing)]
@@ -52,7 +55,8 @@ impl Sample {
             barcode.as_bytes().iter().all(|&b| is_valid_base(b)),
             "All sample barcode bases must be one of A, C, G, or T"
         );
-        Self { sample_id: name, barcode, ordinal }
+        let barcode_bytes = barcode.as_bytes().to_vec();
+        Self { sample_id: name, barcode, barcode_bytes, ordinal }
     }
 
     /// Returns the header line expected by serde when deserializing
@@ -293,11 +297,7 @@ mod tests {
         let barcode = "GATTACA".to_owned();
         let ordinal = 0;
         let sample = Sample::new(ordinal, name.clone(), barcode.clone());
-        assert_eq!(
-            Sample { sample_id: name, barcode, ordinal },
-            sample,
-            "Sample differed from expectation"
-        );
+        assert_eq!(Sample::new(ordinal, name, barcode), sample, "Sample differed from expectation");
     }
 
     // ############################################################################################