Merge branch 'ar/make-options-consistent' into 'master'

refactor(cli): make options more consistent

See merge request machine-learning/modkit!301

Author: ArtRand

book/src/advanced_usage.md

@@ -219,7 +219,7 @@ Filtering Options:
           --filter-threshold 0.9 will specify a threshold value of 0.70 for
           adenine and 0.9 for all other base modification calls
 
-      --mod-thresholds <MOD_THRESHOLDS>
+      --mod-threshold <MOD_THRESHOLDS>
           Specify a passing threshold to use for a base modification,
           independent of the threshold for the primary sequence base or the
           default. For example, to set the pass threshold for 5hmC to 0.8 use
@@ -414,7 +414,7 @@ Selection Options:
       --filter-probs
           Filter out the lowest confidence base modification probabilities
 
-      --only-mapped
+      --mapped-only
           Only use base modification probabilities from bases that are aligned
           when estimating the filter threshold (i.e. ignore soft-clipped, and
           inserted bases)
@@ -620,7 +620,7 @@ Selection Options:
           Only sample base modification probabilities that are aligned to the
           positions in this BED file. (alias: include-positions)
 
-      --only-mapped
+      --mapped-only
           Only use base modification probabilities that are aligned (i.e. ignore
           soft-clipped, and inserted bases)
 
@@ -738,7 +738,7 @@ Filtering Options:
           --filter-threshold 0.9 will specify a threshold value of 0.70 for
           adenine and 0.9 for all other base modification calls
 
-      --mod-thresholds <MOD_THRESHOLDS>
+      --mod-threshold <MOD_THRESHOLDS>
           Specify a passing threshold to use for a base modification,
           independent of the threshold for the primary sequence base or the
           default. For example, to set the pass threshold for 5hmC to 0.8 use
@@ -775,7 +775,7 @@ Selection Options:
           Only summarize base modification probabilities that are aligned to the
           positions in this BED file. (alias: include-positions)
 
-      --only-mapped
+      --mapped-only
           Only use base modification probabilities that are aligned (i.e. ignore
           soft-clipped, and inserted bases)
 
@@ -1218,7 +1218,7 @@ Filtering Options:
           --filter-threshold 0.9 will specify a threshold value of 0.70 for
           adenine and 0.9 for all other base modification calls
 
-      --mod-thresholds <MOD_THRESHOLDS>
+      --mod-threshold <MOD_THRESHOLDS>
           Specify a passing threshold to use for a base modification,
           independent of the threshold for the primary sequence base or the
           default. For example, to set the pass threshold for 5hmC to 0.8 use
@@ -1358,10 +1358,10 @@ Filtering Options:
       --filter-threshold <FILTER_THRESHOLD>
           Specify the filter threshold globally or for the canonical calls. When
           specified, base modification call probabilities will be required to be
-          greater than or equal to this number. If `--mod-thresholds` is also
+          greater than or equal to this number. If `--mod-threshold` is also
           specified, _this_ value will be used for canonical calls
 
-      --mod-thresholds <MOD_THRESHOLDS>
+      --mod-threshold <MOD_THRESHOLDS>
           Specify a passing threshold to use for a base modification,
           independent of the threshold for the primary sequence base or the
           default. For example, to set the pass threshold for 5hmC to 0.8 use
@@ -1930,7 +1930,7 @@ Filtering Options:
           --filter-threshold 0.9 will specify a threshold value of 0.70 for
           adenine and 0.9 for all other base modification calls
 
-      --mod-thresholds <MOD_THRESHOLDS>
+      --mod-threshold <MOD_THRESHOLDS>
           Specify a passing threshold to use for a base modification,
           independent of the threshold for the primary sequence base or the
           default. For example, to set the pass threshold for 5hmC to 0.8 use
@@ -2812,7 +2812,7 @@ Selection Options:
           Check tags on non-primary alignments as well. Keep in mind this may
           incur a double-counting of the read with its primary mapping
 
-      --only-mapped
+      --mapped-only
           Only check alignments that are mapped
 
       --region <REGION>

book/src/filtering.md

@@ -6,7 +6,7 @@ Threshold values for modifications on a primary sequence base can be specified o
 For example to set a threshold for cytosine modifications at 0.8 and adenine modifications at 0.9 provide `--filter-threshold C:0.8 --filter-threshold A:0.9`.
 Pass threshold values per base modification can also be specified.
 For example, to specify a threshold for canonical adenine at 0.8 and 6mA at 0.9 use `--filter-threshold A:0.8 --mod-thresholds a:0.9`.
-Or to specify a threshold of 0.8 for 5mC, 0.9 for 5hmC, and 0.85 for canonical cytosine: `--filter-threshold C:0.85 --mod-thresholds m:0.8 --mod-thresholds h:0.9`
+Or to specify a threshold of 0.8 for 5mC, 0.9 for 5hmC, and 0.85 for canonical cytosine: `--filter-threshold C:0.85 --mod-threshold m:0.8 --mod-threshold h:0.9`
 
 Keep in mind that the `--mod-threshold` option will treat `A`, `C`, `G`, and `T` and "any-mod" as per the [specification](https://samtools.github.io/hts-specs/SAMtags.pdf).
 

modkit-core/src/entropy/subcommand.rs

@@ -86,7 +86,7 @@ pub struct MethylationEntropy {
     filter_percentile: f32,
     /// Specify the filter threshold globally or for the canonical calls.
     /// When specified, base modification call probabilities will be required
-    /// to be greater than or equal to this number. If `--mod-thresholds`
+    /// to be greater than or equal to this number. If `--mod-threshold`
     /// is also specified, _this_ value will be used for canonical calls.
     #[clap(help_heading = "Filtering Options")]
     #[arg(
@@ -105,8 +105,8 @@ pub struct MethylationEntropy {
     /// See the online documentation for more details.
     #[clap(help_heading = "Filtering Options")]
     #[arg(
-        long,
-        alias = "mod-threshold",
+        long = "mod-threshold",
+        alias = "mod-thresholds",
         action = clap::ArgAction::Append
     )]
     mod_thresholds: Option<Vec<String>>,

modkit-core/src/extract/subcommand.rs

@@ -389,8 +389,8 @@ pub struct EntryExtractCalls {
     /// See the online documentation for more details.
     #[clap(help_heading = "Filtering Options")]
     #[arg(
-        long,
-        alias = "mod-threshold",
+        long = "mod-threshold",
+        alias = "mod-thresholds",
         action = clap::ArgAction::Append,
         hide_short_help = true
     )]

modkit-core/src/modbam_util/subcommands.rs

@@ -102,7 +102,11 @@ pub struct EntryCheckTags {
     allow_non_primary: bool,
     /// Only check alignments that are mapped.
     #[clap(help_heading = "Selection Options")]
-    #[arg(long, default_value_t = false)]
+    #[arg(
+        long = "mapped-only",
+        alias = "only-mapped",
+        default_value_t = false
+    )]
     only_mapped: bool,
 
     /// Process only the specified region of the BAM when collecting

modkit-core/src/pileup/subcommand.rs

@@ -180,8 +180,8 @@ pub struct ModBamPileup {
     /// See the online documentation for more details.
     #[clap(help_heading = "Filtering Options")]
     #[arg(
-    long,
-    alias = "mod-threshold",
+    long = "mod-threshold",
+    alias = "mod-thresholds",
     action = clap::ArgAction::Append
     )]
     mod_thresholds: Option<Vec<String>>,
@@ -990,8 +990,8 @@ pub struct DuplexModBamPileup {
     /// See the online documentation for more details.
     #[clap(help_heading = "Filtering Options")]
     #[arg(
-    long,
-    alias = "mod-threshold",
+    long = "mod-threshold",
+    alias = "mod-thresholds",
     action = clap::ArgAction::Append
     )]
     mod_thresholds: Option<Vec<String>>,

modkit/src/commands.rs

@@ -341,6 +341,7 @@ pub struct Adjust {
     #[arg(
         requires="filter_probs",
         long = "mod-threshold",
+        alias = "mod-thresholds",
         action = clap::ArgAction::Append,
         hide_short_help = true,
     )]
@@ -350,7 +351,8 @@ pub struct Adjust {
     /// inserted bases).
     #[clap(help_heading = "Selection Options")]
     #[arg(
-        long,
+        long = "mapped-only",
+        alias = "only-mapped",
         default_value_t = false,
         hide_short_help = true,
         conflicts_with = "filter_percentile",
@@ -669,7 +671,12 @@ pub struct SampleModBaseProbs {
     sampling_frac: Option<f64>,
     /// No sampling, use all of the reads to calculate the filter thresholds.
     #[clap(help_heading = "Sampling Options")]
-    #[arg(long, group = "sampling_options", default_value_t = false)]
+    #[arg(
+        long,
+        alias = "no_filtering",
+        group = "sampling_options",
+        default_value_t = false
+    )]
     no_sampling: bool,
     /// Random seed for deterministic running, the default is
     /// non-deterministic, only used when no BAM index is provided.
@@ -697,7 +704,11 @@ pub struct SampleModBaseProbs {
     /// Only use base modification probabilities that are aligned (i.e. ignore
     /// soft-clipped, and inserted bases).
     #[clap(help_heading = "Selection Options")]
-    #[arg(long, default_value_t = false)]
+    #[arg(
+        long = "mapped-only",
+        alias = "only-mapped",
+        default_value_t = false
+    )]
     only_mapped: bool,
 }
 
@@ -1002,7 +1013,8 @@ pub struct ModSummarize {
     /// See the online documentation for more details.
     #[clap(help_heading = "Filtering Options")]
     #[arg(
-    long,
+    long = "mod-threshold",
+    alias = "mod-thresholds",
     action = clap::ArgAction::Append
     )]
     mod_thresholds: Option<Vec<String>>,
@@ -1038,9 +1050,13 @@ pub struct ModSummarize {
     include_bed: Option<PathBuf>,
     /// Only use base modification probabilities that are aligned (i.e. ignore
     /// soft-clipped, and inserted bases).
-    #[clap(help_heading = "Selection Options")]
+    #[clap(
+        long = "mapped-only",
+        alias = "only-mapped",
+        help_heading = "Selection Options"
+    )]
     #[arg(long, default_value_t = false)]
-    only_mapped: bool,
+    mapped_only: bool,
 
     /// Process only the specified region of the BAM when collecting
     /// probabilities. Format should be <chrom_name>:<start>-<end> or
@@ -1145,7 +1161,7 @@ impl ModSummarize {
                         collapse_method.as_ref(),
                         edge_filter.as_ref(),
                         position_filter.as_ref(),
-                        self.only_mapped || position_filter.is_some(),
+                        self.mapped_only || position_filter.is_some(),
                         false,
                         None,
                         None,
@@ -1165,7 +1181,7 @@ impl ModSummarize {
                     collapse_method.as_ref(),
                     edge_filter.as_ref(),
                     position_filter.as_ref(),
-                    self.only_mapped || position_filter.is_some(),
+                    self.mapped_only || position_filter.is_some(),
                     self.suppress_progress,
                 )?
             };
@@ -1520,7 +1536,9 @@ pub struct CallMods {
     /// unless the `--filter-threshold` option is also passed.
     /// See the online documentation for more details.
     #[arg(
+    long,
     long = "mod-threshold",
+    alias = "mod-thresholds",
     action = clap::ArgAction::Append
     )]
     mod_thresholds: Option<Vec<String>>,