Merge branch 'ar/changelog050' into 'master'

Updates Changelog for v0.5.0

See merge request machine-learning/modkit!286

Author: ArtRand

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.5.0]
+### Adds
+- [open-chromatin] Adds open chromatin prediction subcommand for 6mA MTase-treated DNA
+- [all] Fallback to ML 254 when threshold is estimated as 1.0
+### Changes
+- [all] Refactor to workspaces
+- [modbam, check-tags] Adds `--head <n>` option to take first `n` reads
+### Fixes 
+- [stats] Allow BED5 input regions and header/comment lines
+
 ## [v0.4.4]
 ### Adds
 - [extract] Adds alignment start and end columns

book/src/advanced_usage.md

@@ -15,58 +15,60 @@ Nanopore
 Usage: modkit <COMMAND>
 
 Commands:
-  pileup        Tabulates base modification calls across genomic positions. This
-                command produces a bedMethyl formatted file. Schema and
-                description of fields can be found in the README
-  adjust-mods   Performs various operations on BAM files containing base
-                modification information, such as converting base modification
-                codes and ignoring modification calls. Produces a BAM output
-                file
-  update-tags   Renames Mm/Ml to tags to MM/ML. Also allows changing the mode
-                flag from silent '.' to explicitly '?' or '.'
-  sample-probs  Calculate an estimate of the base modification probability
-                distribution
-  summary       Summarize the mod tags present in a BAM and get basic
-                statistics. The default output is a totals table (designated by
-                '#' lines) and a modification calls table. Descriptions of the
-                columns can be found in the README
-  call-mods     Call mods from a modbam, creates a new modbam with probabilities
-                set to 100% if a base modification is called or 0% if called
-                canonical
-  extract       Extract read-level base modification information from a modBAM
-                into a tab-separated values table
-  repair        Repair MM and ML tags in one bam with the correct tags from
-                another. To use this command, both modBAMs _must_ be sorted by
-                read name. The "donor" modBAM's reads must be a superset of the
-                acceptor's reads. Extra reads in the donor are allowed, and
-                multiple reads with the same name (secondary, etc.) are allowed
-                in the acceptor. Reads with an empty SEQ field cannot be
-                repaired and will be rejected. Reads where there is an ambiguous
-                alignment of the acceptor to the donor will be rejected (and
-                logged). See the full documentation for details
-  dmr           Perform DMR test on a set of regions. Output a BED file of
-                regions with the score column indicating the magnitude of the
-                difference. Find the schema and description of fields can in the
-                README as well as a description of the model and method. See
-                subcommand help for additional details
-  pileup-hemi   Tabulates double-stranded base modification patters (such as
-                hemi-methylation) across genomic motif positions. This command
-                produces a bedMethyl file, the schema can be found in the online
-                documentation
-  validate      Validate results from a set of mod-BAM files and associated BED
-                files containing the ground truth modified base status at
-                reference positions
-  motif         Various commands to search for, evaluate, or further regine
-                sequence motifs enriched for base modification. Also can
-                generate BED files of motif locations
-  entropy       Use a mod-BAM to calculate methylation entropy over genomic
-                windows
-  localize      Investigate patterns of base modifications, by aggregating
-                pileup counts "localized" around genomic features of interest
-  stats         Calculate base modification levels over regions
-  bedmethyl     Utilities to work with bedMethyl files
-  modbam        Utilities to work with modBAM files
-  help          Print this message or the help of the given subcommand(s)
+  pileup          Tabulates base modification calls across genomic positions.
+                  This command produces a bedMethyl formatted file. Schema and
+                  description of fields can be found in the README
+  adjust-mods     Performs various operations on BAM files containing base
+                  modification information, such as converting base modification
+                  codes and ignoring modification calls. Produces a BAM output
+                  file
+  update-tags     Renames Mm/Ml to tags to MM/ML. Also allows changing the mode
+                  flag from silent '.' to explicitly '?' or '.'
+  sample-probs    Calculate an estimate of the base modification probability
+                  distribution
+  summary         Summarize the mod tags present in a BAM and get basic
+                  statistics. The default output is a totals table (designated
+                  by '#' lines) and a modification calls table. Descriptions of
+                  the columns can be found in the README
+  call-mods       Call mods from a modbam, creates a new modbam with
+                  probabilities set to 100% if a base modification is called or
+                  0% if called canonical
+  extract         Extract read-level base modification information from a modBAM
+                  into a tab-separated values table
+  repair          Repair MM and ML tags in one bam with the correct tags from
+                  another. To use this command, both modBAMs _must_ be sorted by
+                  read name. The "donor" modBAM's reads must be a superset of
+                  the acceptor's reads. Extra reads in the donor are allowed,
+                  and multiple reads with the same name (secondary, etc.) are
+                  allowed in the acceptor. Reads with an empty SEQ field cannot
+                  be repaired and will be rejected. Reads where there is an
+                  ambiguous alignment of the acceptor to the donor will be
+                  rejected (and logged). See the full documentation for details
+  dmr             Perform DMR test on a set of regions. Output a BED file of
+                  regions with the score column indicating the magnitude of the
+                  difference. Find the schema and description of fields can in
+                  the README as well as a description of the model and method.
+                  See subcommand help for additional details
+  pileup-hemi     Tabulates double-stranded base modification patters (such as
+                  hemi-methylation) across genomic motif positions. This command
+                  produces a bedMethyl file, the schema can be found in the
+                  online documentation
+  validate        Validate results from a set of mod-BAM files and associated
+                  BED files containing the ground truth modified base status at
+                  reference positions
+  motif           Various commands to search for, evaluate, or further regine
+                  sequence motifs enriched for base modification. Also can
+                  generate BED files of motif locations
+  entropy         Use a mod-BAM to calculate methylation entropy over genomic
+                  windows
+  localize        Investigate patterns of base modifications, by aggregating
+                  pileup counts "localized" around genomic features of interest
+  stats           Calculate base modification levels over regions
+  bedmethyl       Utilities to work with bedMethyl files
+  modbam          Utilities to work with modBAM files
+  open-chromatin  Identify regions of open chromatin based on exogenous 6mA
+                  signal
+  help            Print this message or the help of the given subcommand(s)
 
 Options:
   -h, --help     Print help
@@ -1507,7 +1509,7 @@ Options:
 
 Output Options:
   -o, --out-table <OUT_TABLE>  Specify the output file to write the results
-                               table
+                               table, or "-"/"stdout" for stdout
       --force                  Force overwrite the output file
       --no-header              Don't add the header describing the columns to
                                the output
@@ -1521,6 +1523,73 @@ Compute Options:
                                  2]
 ```
 
+## open-chromatin predict
+```text
+Usage: modkit open-chromatin predict [OPTIONS] --model <MODEL_PATH> --output <OUTPUT> <IN_BAM>
+
+Arguments:
+  <IN_BAM>
+          Input modBAM with 6mA base modification calls
+
+Options:
+      --model <MODEL_PATH>
+          Path to directory with open-chromatin model
+
+      --batch-size <BATCH_SIZE>
+          Collect this many windows of data for each run through the model
+          
+          [default: 1024]
+
+      --super-batch-size <SUPER_BATCH_SIZE>
+          Number of "batches" to collect at once, see documentation for exact
+          calculation or run with --dryrun to see output
+          
+          [default: 100]
+
+      --step-size <STEP_SIZE>
+          Number of base pairs to step along the genome or genomic intervals to
+          make predictions. Smaller numbers will result in better resolution but
+          take more computation
+          
+          [default: 25]
+
+  -t, --min-coverage <MIN_COVERAGE>
+          Require this many reads covering each prediction window
+          
+          [default: 5]
+
+      --threshold <FILTER_THRESHOLD>
+          Only emit records/windows where the open chromatin probability is
+          greater than or equal to this value
+
+  -o, --output <OUTPUT>
+          Output bedGraph file, or "-"/"stdout" to write to stdout
+
+      --force
+          Force overwrite output file
+
+      --log-filepath <LOG_FILEPATH>
+          Path to file to write logs to, setting this parameter is recommended
+
+      --include-bed <INCLUDE_BED>
+          BED file of regions over which to make predictions
+
+      --region <REGION>
+          Region in the format <chrom>:start-end over which to make predictions
+
+      --suppress-progress
+          Hide the progress bar
+
+      --no-header
+          Don't print header in output
+
+      --dryrun
+          Perform setup and validations, but stop before performing inference
+
+  -h, --help
+          Print help (see a summary with '-h')
+```
+
 ## extract full
 ```text
 Transform the probabilities from the MM/ML tags in a modBAM into a table
@@ -2750,4 +2819,8 @@ Selection Options:
           Process only the specified region of the BAM when collecting
           probabilities. Format should be <chrom_name>:<start>-<end> or
           <chrom_name>
+
+      --head <HEAD>
+          Use the first N reads without sampling. Shorthand for --ignore-index
+          --num-reads N
 ```