feat: replace curve_power with deadzone

Author: St4NNi

src/bias.rs

@@ -225,7 +225,8 @@ pub struct BiasCreateConfig {
     pub target_negative_retention: Option<f32>,
     pub positive_fscale: Option<u64>,
     pub negative_fscale: Option<u64>,
-    pub curve_power: f32,
+    pub deadzone_pos: f32,
+    pub deadzone_neg: f32,
 }
 
 #[derive(Debug, Clone, Copy)]
@@ -251,7 +252,8 @@ pub struct HashBiasTable {
     pub negative_fscale: u64,
     pub k_pos: f32,
     pub k_neg: f32,
-    pub curve_power: f32,
+    pub deadzone_pos: f32,
+    pub deadzone_neg: f32,
 }
 
 #[derive(Debug, Clone, Copy)]
@@ -365,7 +367,8 @@ impl HashBiasTable {
             config.target_negative_retention,
             config.positive_fscale.unwrap_or(0),
             config.negative_fscale.unwrap_or(0),
-            config.curve_power,
+            config.deadzone_pos,
+            config.deadzone_neg,
         )?;
 
         if let Some(ref pb) = progress {
@@ -384,16 +387,20 @@ impl HashBiasTable {
         target_negative_retention: Option<f32>,
         positive_fscale: u64,
         negative_fscale: u64,
-        curve_power: f32,
+        deadzone_pos: f32,
+        deadzone_neg: f32,
     ) -> Result<Self> {
         validate_cms_compatibility(positive, negative)?;
 
         if !alpha.is_finite() || alpha <= 0.0 {
             anyhow::bail!("alpha must be finite and > 0, got {}", alpha);
         }
 
-        if !curve_power.is_finite() || curve_power <= 0.0 {
-            anyhow::bail!("curve_power must be finite and > 0, got {}", curve_power);
+        if !deadzone_pos.is_finite() || !(0.0..1.0).contains(&deadzone_pos) {
+            anyhow::bail!("deadzone_pos must be finite and in [0.0, 1.0), got {}", deadzone_pos);
+        }
+        if !deadzone_neg.is_finite() || !(0.0..1.0).contains(&deadzone_neg) {
+            anyhow::bail!("deadzone_neg must be finite and in [0.0, 1.0), got {}", deadzone_neg);
         }
 
         if let Some(target) = target_positive_retention {
@@ -475,7 +482,8 @@ impl HashBiasTable {
             negative_fscale,
             k_pos: 0.0,
             k_neg: 0.0,
-            curve_power,
+            deadzone_pos,
+            deadzone_neg,
         };
 
         // Auto-derive k_pos and k_neg when soft filter is active
@@ -680,14 +688,20 @@ impl HashBiasTable {
 
     /// Compute the effective fscale using piecewise sigmoid centered at 0.
     /// w >= 0 uses k_pos, w < 0 uses k_neg. At w=0: s=0.5 → geometric mean (midpoint anchor).
-    /// When curve_power > 1.0, a power transform flattens the sigmoid's middle region,
-    /// so only strongly biased k-mers get preferential/penalized treatment.
+    /// deadzone_pos/deadzone_neg define the fraction of each side's weight range that stays
+    /// flat (no effect) before the sigmoid transition kicks in.
     #[inline]
     fn effective_fscale(&self, w: i8) -> f64 {
         let k = if w >= 0 { self.k_pos } else { self.k_neg };
+        let deadzone = if w >= 0 { self.deadzone_pos } else { self.deadzone_neg } as f64;
         let w_norm = w as f64 / 127.0;
-        let w_curved = w_norm.signum() * w_norm.abs().powf(self.curve_power as f64);
-        let x = k as f64 * w_curved * 127.0;
+        let abs_w = w_norm.abs();
+        let remapped = if abs_w <= deadzone {
+            0.0
+        } else {
+            (abs_w - deadzone) / (1.0 - deadzone)
+        };
+        let x = k as f64 * w_norm.signum() * remapped * 127.0;
         let s = 1.0 / (1.0 + (-x).exp());
         let log_pos = (self.positive_fscale as f64).ln();
         let log_neg = (self.negative_fscale as f64).ln();
@@ -748,7 +762,8 @@ impl HashBiasTable {
         file.write_all(&self.negative_fscale.to_le_bytes())?;
         file.write_all(&self.k_pos.to_le_bytes())?;
         file.write_all(&self.k_neg.to_le_bytes())?;
-        file.write_all(&self.curve_power.to_le_bytes())?;
+        file.write_all(&self.deadzone_pos.to_le_bytes())?;
+        file.write_all(&self.deadzone_neg.to_le_bytes())?;
 
         for &seed in &self.seeds {
             file.write_all(&seed.to_le_bytes())?;
@@ -826,7 +841,10 @@ impl HashBiasTable {
         let k_neg = f32::from_le_bytes(buf4);
 
         file.read_exact(&mut buf4)?;
-        let curve_power = f32::from_le_bytes(buf4);
+        let deadzone_pos = f32::from_le_bytes(buf4);
+
+        file.read_exact(&mut buf4)?;
+        let deadzone_neg = f32::from_le_bytes(buf4);
 
         let mut seeds = Vec::with_capacity(depth);
         for _ in 0..depth {
@@ -867,12 +885,13 @@ impl HashBiasTable {
             negative_fscale,
             k_pos,
             k_neg,
-            curve_power,
+            deadzone_pos,
+            deadzone_neg,
         })
     }
 
     pub fn to_bytes(&self) -> Vec<u8> {
-        let header_size = 4 + 4 + 1 + 8 + 4 + 1 + 4 + 1 + 4 + 4 + 8 + 8 + 4 + 4 + 4; // 63 bytes
+        let header_size = 4 + 4 + 1 + 8 + 4 + 1 + 4 + 1 + 4 + 4 + 8 + 8 + 4 + 4 + 4 + 4; // 67 bytes
         let seeds_size = self.config.depth * 8;
         let weights_size = self.config.width * self.config.depth;
         let total_size = header_size + seeds_size + weights_size;
@@ -892,7 +911,8 @@ impl HashBiasTable {
         out.extend_from_slice(&self.negative_fscale.to_le_bytes());
         out.extend_from_slice(&self.k_pos.to_le_bytes());
         out.extend_from_slice(&self.k_neg.to_le_bytes());
-        out.extend_from_slice(&self.curve_power.to_le_bytes());
+        out.extend_from_slice(&self.deadzone_pos.to_le_bytes());
+        out.extend_from_slice(&self.deadzone_neg.to_le_bytes());
 
         for &seed in &self.seeds {
             out.extend_from_slice(&seed.to_le_bytes());
@@ -938,9 +958,10 @@ impl HashBiasTable {
         let negative_fscale = u64::from_le_bytes(data[43..51].try_into().unwrap());
         let k_pos = f32::from_le_bytes(data[51..55].try_into().unwrap());
         let k_neg = f32::from_le_bytes(data[55..59].try_into().unwrap());
-        let curve_power = f32::from_le_bytes(data[59..63].try_into().unwrap());
+        let deadzone_pos = f32::from_le_bytes(data[59..63].try_into().unwrap());
+        let deadzone_neg = f32::from_le_bytes(data[63..67].try_into().unwrap());
 
-        let seeds_start = 63;
+        let seeds_start = 67;
         let seeds_end = seeds_start + depth * 8;
         let weights_start = seeds_end;
         let weights_end = weights_start + width * depth;
@@ -992,7 +1013,8 @@ impl HashBiasTable {
             negative_fscale,
             k_pos,
             k_neg,
-            curve_power,
+            deadzone_pos,
+            deadzone_neg,
         })
     }
 
@@ -1087,7 +1109,8 @@ impl HashBiasTable {
         if self.is_soft_filter() {
             eprintln!("  k_pos:               {:.4}", self.k_pos);
             eprintln!("  k_neg:               {:.4}", self.k_neg);
-            eprintln!("  curve_power:         {:.2}", self.curve_power);
+            eprintln!("  deadzone_pos:        {:.2}", self.deadzone_pos);
+            eprintln!("  deadzone_neg:        {:.2}", self.deadzone_neg);
 
             eprintln!("  reference points:");
             for p in self.soft_filter_reference_points() {
@@ -1388,7 +1411,8 @@ impl PartialEq for HashBiasTable {
             && self.negative_fscale == other.negative_fscale
             && self.k_pos == other.k_pos
             && self.k_neg == other.k_neg
-            && self.curve_power == other.curve_power
+            && self.deadzone_pos == other.deadzone_pos
+            && self.deadzone_neg == other.deadzone_neg
             && self.seeds == other.seeds
             && self.weights == other.weights
     }
@@ -1499,7 +1523,7 @@ mod tests {
         )
         .unwrap();
 
-        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 1.0).unwrap();
+        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 0.0, 0.0).unwrap();
         assert!(table.threshold >= -127);
     }
 
@@ -1530,7 +1554,7 @@ mod tests {
         )
         .unwrap();
 
-        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 1.0).unwrap();
+        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 0.0, 0.0).unwrap();
 
         let output = NamedTempFile::new().unwrap();
         table.save(output.path()).unwrap();
@@ -1568,7 +1592,7 @@ mod tests {
         )
         .unwrap();
 
-        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 1.0).unwrap();
+        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 0.0, 0.0).unwrap();
 
         let bytes = table.to_bytes();
         let loaded = HashBiasTable::from_bytes(&bytes).unwrap();
@@ -1603,7 +1627,7 @@ mod tests {
         )
         .unwrap();
 
-        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 1.0).unwrap();
+        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 0.0, 0.0).unwrap();
 
         let mut passed = 0;
         let mut failed = 0;
@@ -1651,7 +1675,7 @@ mod tests {
         )
         .unwrap();
 
-        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 1.0).unwrap();
+        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 0.0, 0.0).unwrap();
         assert!(table.threshold >= -127);
         assert!(table.fold_enrichment() >= 1.0);
     }
@@ -1673,7 +1697,8 @@ mod tests {
             target_negative_retention: None,
             positive_fscale: None,
             negative_fscale: None,
-            curve_power: 1.0,
+            deadzone_pos: 0.0,
+            deadzone_neg: 0.0,
         };
 
         let table = HashBiasTable::create(&[pos.path()], &[neg.path()], &config, None).unwrap();
@@ -1716,7 +1741,7 @@ mod tests {
         .unwrap();
 
         // Hard cutoff mode (positive_fscale=0, negative_fscale=0)
-        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 1.0).unwrap();
+        let table = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 0, 0.0, 0.0).unwrap();
         assert!(!table.is_soft_filter());
 
         // Verify passes_filter matches weight >= threshold for many hashes
@@ -1761,7 +1786,7 @@ mod tests {
         .unwrap();
 
         let table =
-            HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 1, 1000, 1.0).unwrap();
+            HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 1, 1000, 0.0, 0.0).unwrap();
         assert!(table.is_soft_filter());
 
         // Same hash always gives the same result
@@ -1800,7 +1825,7 @@ mod tests {
         .unwrap();
 
         let table =
-            HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 10, 5000, 1.0).unwrap();
+            HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 10, 5000, 0.0, 0.0).unwrap();
         assert!(table.is_soft_filter());
 
         let bytes = table.to_bytes();
@@ -1836,7 +1861,7 @@ mod tests {
         .unwrap();
 
         let table =
-            HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 10_000, 1.0).unwrap();
+            HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 10_000, 0.0, 0.0).unwrap();
         assert!(table.is_soft_filter());
 
         let expected = (100.0_f64 * 10_000.0_f64).sqrt();
@@ -1872,23 +1897,23 @@ mod tests {
         .unwrap();
 
         // positive_fscale < global fscale → error
-        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 50, 1000, 1.0);
+        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 50, 1000, 0.0, 0.0);
         assert!(result.is_err());
 
         // positive_fscale without negative_fscale → error
-        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 0, 1.0);
+        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 0, 0.0, 0.0);
         assert!(result.is_err());
 
         // negative_fscale without positive_fscale → error
-        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 1000, 1.0);
+        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 0, 1000, 0.0, 0.0);
         assert!(result.is_err());
 
         // negative_fscale <= positive_fscale → error
-        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 100, 1.0);
+        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 100, 0.0, 0.0);
         assert!(result.is_err());
 
         // Valid soft filter
-        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 5000, 1.0);
+        let result = HashBiasTable::build(&pos_raw, &neg_raw, 1.0, None, None, 100, 5000, 0.0, 0.0);
         assert!(result.is_ok());
     }
 }

src/cli/args.rs

@@ -154,10 +154,16 @@ pub enum BiasCommands {
         /// Use "drop" to discard hashes below the threshold.
         #[arg(long)]
         negative_fscale: Option<String>,
-        /// Power exponent for sigmoid curve shaping (>1 flattens the middle,
-        /// so only strongly biased k-mers get preferential treatment).
-        #[arg(long, default_value = "1.0")]
-        curve_power: f32,
+        /// Deadzone fraction for positively biased k-mers (0.0–1.0).
+        /// Fraction of positive weight range that stays flat before sigmoid kicks in.
+        /// E.g. 0.95 means only the top 5% of positively biased k-mers get boosted.
+        #[arg(long, default_value = "0.0")]
+        deadzone_pos: f32,
+        /// Deadzone fraction for negatively biased k-mers (0.0–1.0).
+        /// Fraction of negative weight range that stays flat before sigmoid kicks in.
+        /// E.g. 0.0 means transition starts immediately (cliff behavior with high k_neg).
+        #[arg(long, default_value = "0.0")]
+        deadzone_neg: f32,
         /// Number of threads to use for bias sketching
         #[arg(long)]
         threads: Option<usize>,

src/cli/handlers.rs

@@ -357,7 +357,8 @@ pub fn handle_bias_create_command(
     negative_retention: Option<f32>,
     positive_fscale: Option<u64>,
     negative_fscale: Option<String>,
-    curve_power: f32,
+    deadzone_pos: f32,
+    deadzone_neg: f32,
     threads: Option<usize>,
     force: bool,
     silent: bool,
@@ -388,8 +389,17 @@ pub fn handle_bias_create_command(
         return Err(anyhow::anyhow!("--alpha must be finite and > 0"));
     }
 
-    if !curve_power.is_finite() || curve_power <= 0.0 {
-        return Err(anyhow::anyhow!("--curve-power must be finite and > 0"));
+    if !deadzone_pos.is_finite() || !(0.0..1.0).contains(&deadzone_pos) {
+        return Err(anyhow::anyhow!(
+            "--deadzone-pos must be finite and in [0.0, 1.0), got {}",
+            deadzone_pos
+        ));
+    }
+    if !deadzone_neg.is_finite() || !(0.0..1.0).contains(&deadzone_neg) {
+        return Err(anyhow::anyhow!(
+            "--deadzone-neg must be finite and in [0.0, 1.0), got {}",
+            deadzone_neg
+        ));
     }
 
     if let Some(v) = positive_retention
@@ -461,7 +471,8 @@ pub fn handle_bias_create_command(
         target_negative_retention: negative_retention,
         positive_fscale,
         negative_fscale,
-        curve_power,
+        deadzone_pos,
+        deadzone_neg,
     };
 
     let pos_paths: Vec<&std::path::Path> = positive.iter().map(|p| p.as_path()).collect();
@@ -532,7 +543,8 @@ pub fn handle_bias_create_command(
         if table.is_soft_filter() {
             eprintln!("  k_pos:               {:.4}", table.k_pos);
             eprintln!("  k_neg:               {:.4}", table.k_neg);
-            eprintln!("  curve_power:         {:.2}", table.curve_power);
+            eprintln!("  deadzone_pos:        {:.2}", table.deadzone_pos);
+            eprintln!("  deadzone_neg:        {:.2}", table.deadzone_neg);
             eprintln!("  reference points:");
             for p in table.soft_filter_reference_points() {
                 eprintln!(
@@ -630,7 +642,8 @@ pub fn handle_bias_stats_command(
                 "negative_fscale_drop": table.negative_fscale == u64::MAX,
                 "k_pos": table.k_pos,
                 "k_neg": table.k_neg,
-                "curve_power": table.curve_power,
+                "deadzone_pos": table.deadzone_pos,
+                "deadzone_neg": table.deadzone_neg,
             },
             "weight_stats": {
                 "min": min,