Merge pull request #1682 from dib-lab/doc/cli_usage

Add to CLI usage information

khmer/khmer_args.py

@@ -83,7 +83,9 @@ class CitationAction(argparse.Action):
 
     def __init__(self, *args, **kwargs):
         self.citations = kwargs.pop('citations')
-        super(CitationAction, self).__init__(*args, nargs=0, **kwargs)
+        super(CitationAction, self).__init__(*args, nargs=0,
+                                             default=argparse.SUPPRESS,
+                                             **kwargs)
 
     def __call__(self, parser, namespace, values, option_string=None):
         info(parser.prog, self.citations)
@@ -137,6 +139,7 @@ def __init__(self, citations=None, formatter_class=ComboFormatter,
         self.add_argument('--version', action=_VersionStdErrAction,
                           version='khmer {v}'.format(v=__version__))
         self.add_argument('--info', action=CitationAction,
+                          help='print citation information',
                           citations=self._citations)
         self.add_argument('-h', '--help', action=_HelpAction,
                           default=argparse.SUPPRESS,
@@ -439,7 +442,7 @@ def build_graph_args(descr=None, epilog=None, parser=None, citations=None):
         parser = KhmerArgumentParser(description=descr, epilog=epilog,
                                      citations=citations)
 
-    parser.add_argument('--ksize', '-k', type=int, default=DEFAULT_K,
+    parser.add_argument('-k', '--ksize', type=int, default=DEFAULT_K,
                         help='k-mer size to use')
 
     help = ('number of tables to use in k-mer countgraph' if expert_help
@@ -615,7 +618,7 @@ def report_on_config(args, graphtype='countgraph'):
 
 def add_threading_args(parser):
     """Add option for threading to options parser."""
-    parser.add_argument('--threads', '-T', default=DEFAULT_N_THREADS, type=int,
+    parser.add_argument('-T', '--threads', default=DEFAULT_N_THREADS, type=int,
                         help='Number of simultaneous threads to execute')
 
 

scripts/abundance-dist-single.py

@@ -94,11 +94,11 @@ def get_parser():
     parser.add_argument('-s', '--squash', dest='squash_output', default=False,
                         action='store_true',
                         help='Overwrite output file if it exists')
-    parser.add_argument('--savegraph', default='', metavar="filename",
+    parser.add_argument('--savegraph', metavar="filename",
                         help="Save the k-mer countgraph to the specified "
                         "filename.")
     parser.add_argument('-f', '--force', default=False, action='store_true',
-                        help='Overwrite output file if it exists')
+                        help='Override sanity checks')
     parser.add_argument('-q', '--quiet', dest='quiet', default=False,
                         action='store_true')
     return parser
@@ -112,7 +112,7 @@ def main():  # pylint: disable=too-many-locals,too-many-branches
     report_on_config(args, graph_type)
 
     check_input_files(args.input_sequence_filename, args.force)
-    if args.savegraph:
+    if args.savegraph is not None:
         graphsize = calculate_graphsize(args, graph_type)
         check_space_for_graph(args.savegraph, graphsize, args.force)
     if (not args.squash_output and
@@ -213,7 +213,7 @@ def __do_abundance_dist__(read_parser):
         if sofar == total:
             break
 
-    if args.savegraph:
+    if args.savegraph is not None:
         log_info('Saving k-mer countgraph to {savegraph}',
                  savegraph=args.savegraph)
         countgraph.save(args.savegraph)

scripts/annotate-partitions.py

@@ -73,7 +73,7 @@ def get_parser():
         description="Annotate sequences with partition IDs.",
         epilog=textwrap.dedent(epilog))
 
-    parser.add_argument('--ksize', '-k', type=int, default=DEFAULT_K,
+    parser.add_argument('-k', '--ksize', type=int, default=DEFAULT_K,
                         help="k-mer size (default: %d)" % DEFAULT_K)
     parser.add_argument('graphbase', help='basename for input and output '
                         'files')

scripts/do-partition.py

@@ -48,7 +48,6 @@
 import threading
 import os.path
 import os
-import gc
 import textwrap
 from khmer import khmer_args
 from khmer.khmer_args import (build_nodegraph_args, report_on_config,
@@ -88,15 +87,14 @@ def get_parser():
         descr='Load, partition, and annotate FAST[AQ] sequences',
         epilog=textwrap.dedent(epilog), citations=['graph'])
     add_threading_args(parser)
-    parser.add_argument('--subset-size', '-s', default=DEFAULT_SUBSET_SIZE,
+    parser.add_argument('-s', '--subset-size', default=DEFAULT_SUBSET_SIZE,
                         dest='subset_size', type=float,
                         help='Set subset size (usually 1e5-1e6 is good)')
     parser.add_argument('--no-big-traverse', dest='no_big_traverse',
                         action='store_true', default=False,
                         help='Truncate graph joins at big traversals')
-    parser.add_argument('--keep-subsets', dest='remove_subsets',
-                        default=True, action='store_false',
-                        help='Keep individual subsets (default: False)')
+    parser.add_argument('--keep-subsets', default=False, action='store_true',
+                        help='Keep individual subsets')
     parser.add_argument('graphbase', help="base name for output files")
     parser.add_argument('input_filenames', metavar='input_sequence_filename',
                         nargs='+', help='input FAST[AQ] sequence filenames')
@@ -212,7 +210,7 @@ def main():  # pylint: disable=too-many-locals,too-many-statements
         print('merging', pmap_file, file=sys.stderr)
         nodegraph.merge_subset_from_disk(pmap_file)
 
-    if args.remove_subsets:
+    if not args.keep_subsets:
         print('removing pmap files', file=sys.stderr)
         for pmap_file in pmap_files:
             os.unlink(pmap_file)

scripts/extract-paired-reads.py

@@ -94,11 +94,11 @@ def get_parser():
     parser.add_argument('-d', '--output-dir', default='', help='Output '
                         'split reads to specified directory. Creates '
                         'directory if necessary')
-    parser.add_argument('--output-paired', '-p', metavar="filename",
+    parser.add_argument('-p', '--output-paired', metavar="filename",
                         type=khFileType('wb'),
                         default=None, help='Output paired reads to this '
                         'file')
-    parser.add_argument('--output-single', '-s', metavar="filename",
+    parser.add_argument('-s', '--output-single', metavar="filename",
                         type=khFileType('wb'), default=None,
                         help='Output orphaned reads to this file')
     parser.add_argument('-f', '--force', default=False, action='store_true',

scripts/extract-partitions.py

@@ -94,16 +94,16 @@ def get_parser():
     parser.add_argument('prefix', metavar='output_filename_prefix')
     parser.add_argument('part_filenames', metavar='input_partition_filename',
                         nargs='+')
-    parser.add_argument('--max-size', '-X', dest='max_size',
+    parser.add_argument('-X', '--max-size', dest='max_size',
                         default=DEFAULT_MAX_SIZE, type=int,
                         help='Max group size (n sequences)')
-    parser.add_argument('--min-partition-size', '-m', dest='min_part_size',
+    parser.add_argument('-m', '--min-partition-size', dest='min_part_size',
                         default=DEFAULT_THRESHOLD, type=int,
                         help='Minimum partition size worth keeping')
-    parser.add_argument('--no-output-groups', '-n', dest='output_groups',
+    parser.add_argument('-n', '--no-output-groups', dest='output_groups',
                         default=True, action='store_false',
                         help='Do not actually output groups files.')
-    parser.add_argument('--output-unassigned', '-U', default=False,
+    parser.add_argument('-U', '--output-unassigned', default=False,
                         action='store_true',
                         help='Output unassigned sequences, too')
     parser.add_argument('-f', '--force', default=False, action='store_true',

scripts/filter-abund-single.py

@@ -90,14 +90,14 @@ def get_parser():
         citations=['counting', 'SeqAn'])
     add_threading_args(parser)
 
-    parser.add_argument('--cutoff', '-C', default=DEFAULT_CUTOFF,
+    parser.add_argument('-C', '--cutoff', default=DEFAULT_CUTOFF,
                         type=check_argument_range(0, 256, "cutoff"),
                         help="Trim at k-mers below this abundance.")
-    parser.add_argument('--variable-coverage', '-V', action='store_true',
+    parser.add_argument('-V', '--variable-coverage', action='store_true',
                         dest='variable_coverage', default=False,
                         help='Only trim low-abundance k-mers from sequences '
                         'that have high coverage.')
-    parser.add_argument('--normalize-to', '-Z', type=int, dest='normalize_to',
+    parser.add_argument('-Z', '--normalize-to', type=int, dest='normalize_to',
                         help='Base the variable-coverage cutoff on this median'
                         ' k-mer abundance.',
                         default=DEFAULT_NORMALIZE_LIMIT)

scripts/filter-abund.py

@@ -87,15 +87,15 @@ def get_parser():
     parser.add_argument('input_filename', metavar='input_sequence_filename',
                         help='Input FAST[AQ] sequence filename', nargs='+')
     add_threading_args(parser)
-    parser.add_argument('--cutoff', '-C', dest='cutoff',
+    parser.add_argument('-C', '--cutoff', dest='cutoff',
                         default=DEFAULT_CUTOFF,
                         type=check_argument_range(0, 256, 'cutoff'),
                         help="Trim at k-mers below this abundance.")
-    parser.add_argument('--variable-coverage', '-V', action='store_true',
+    parser.add_argument('-V', '--variable-coverage', action='store_true',
                         dest='variable_coverage', default=False,
                         help='Only trim low-abundance k-mers from sequences '
                         'that have high coverage.')
-    parser.add_argument('--normalize-to', '-Z', type=int, dest='normalize_to',
+    parser.add_argument('-Z', '--normalize-to', type=int, dest='normalize_to',
                         help='Base the variable-coverage cutoff on this median'
                         ' k-mer abundance.',
                         default=DEFAULT_NORMALIZE_LIMIT)

scripts/filter-stoptags.py

@@ -49,7 +49,7 @@
 import os
 import textwrap
 import sys
-from khmer import __version__, Nodegraph
+from khmer import Nodegraph
 from khmer.thread_utils import ThreadedSequenceProcessor, verbose_loader
 from khmer.kfile import check_input_files, check_space
 from khmer.khmer_args import sanitize_help, KhmerArgumentParser
@@ -67,7 +67,7 @@ def get_parser():
     parser = KhmerArgumentParser(
         description="Trim sequences at stoptags.",
         epilog=textwrap.dedent(epilog), citations=['graph'])
-    parser.add_argument('--ksize', '-k', default=DEFAULT_K, type=int,
+    parser.add_argument('-k', '--ksize', default=DEFAULT_K, type=int,
                         help='k-mer size')
     parser.add_argument('stoptags_file', metavar='input_stoptags_filename')
     parser.add_argument('input_filenames', metavar='input_sequence_filename',

scripts/load-into-counting.py

@@ -93,7 +93,7 @@ def get_parser():
                         action='store_false', help="The default behaviour is "
                         "to count past 255 using bigcount. This flag turns "
                         "bigcount off, limiting counts to 255.")
-    parser.add_argument('--summary-info', '-s', type=str, default=None,
+    parser.add_argument('-s', '--summary-info', type=str, default=None,
                         metavar="FORMAT", choices=[str('json'), str('tsv')],
                         help="What format should the machine readable run "
                         "summary be in? (`json` or `tsv`, disabled by"

scripts/make-initial-stoptags.py

@@ -87,10 +87,10 @@ def get_parser():
         descr="Find an initial set of highly connected k-mers.",
         epilog=textwrap.dedent(epilog),
         citations=['graph'])
-    parser.add_argument('--subset-size', '-s', default=DEFAULT_SUBSET_SIZE,
+    parser.add_argument('-s', '--subset-size', default=DEFAULT_SUBSET_SIZE,
                         dest='subset_size', type=float,
                         help='Set subset size (default 1e4 is prob ok)')
-    parser.add_argument('--stoptags', '-S', metavar='filename', default='',
+    parser.add_argument('-S', '--stoptags', metavar='filename', default='',
                         help="Use stoptags in this file during partitioning")
     parser.add_argument('graphbase', help='basename for input and output '
                         'filenames')

scripts/merge-partitions.py

@@ -65,7 +65,7 @@ def get_parser():
         description="Merge partition map '.pmap' files.",
         epilog=textwrap.dedent(epilog),
         citations=['graph'])
-    parser.add_argument('--ksize', '-k', type=int, default=DEFAULT_K,
+    parser.add_argument('-k', '--ksize', type=int, default=DEFAULT_K,
                         help="k-mer size (default: %d)" % DEFAULT_K)
     parser.add_argument('--keep-subsets', dest='remove_subsets',
                         default=True, action='store_false',

scripts/normalize-by-median.py

@@ -55,13 +55,13 @@
 from khmer import khmer_args
 from contextlib import contextmanager
 from khmer.khmer_args import (build_counting_args, add_loadgraph_args,
-                              report_on_config, info, calculate_graphsize,
+                              report_on_config, calculate_graphsize,
                               sanitize_help, check_argument_range)
 from khmer.khmer_args import FileType as khFileType
 import argparse
 from khmer.kfile import (check_space, check_space_for_graph,
                          check_valid_file_exists, add_output_compression_type,
-                         get_file_writer, is_block, describe_file_handle)
+                         get_file_writer, describe_file_handle)
 from khmer.utils import (write_record, broken_paired_reader, ReadBundle,
                          clean_input_reads)
 from khmer.khmer_logger import (configure_logging, log_info, log_error)
@@ -273,14 +273,15 @@ def get_parser():
                         metavar="unpaired_reads_filename",
                         help='include a file of unpaired reads to which '
                         '-p/--paired does not apply.')
-    parser.add_argument('-s', '--savegraph', metavar="filename", default='',
+    parser.add_argument('-s', '--savegraph', metavar="filename", default=None,
                         help='save the k-mer countgraph to disk after all '
                         'reads are loaded.')
     parser.add_argument('-R', '--report',
+                        help='write progress report to report_filename',
                         metavar='report_filename', type=argparse.FileType('w'))
     parser.add_argument('--report-frequency',
-                        metavar='report_frequency', type=int,
-                        default=100000)
+                        metavar='report_frequency', type=int, default=100000,
+                        help='report progress every report_frequency reads')
     parser.add_argument('-f', '--force', dest='force',
                         help='continue past file reading errors',
                         action='store_true')
@@ -329,7 +330,7 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
     # check that files exist and there is sufficient output disk space.
     check_valid_file_exists(args.input_filenames)
     check_space(args.input_filenames, args.force)
-    if args.savegraph:
+    if args.savegraph is not None:
         graphsize = calculate_graphsize(args, 'countgraph')
         check_space_for_graph(args.savegraph, graphsize, args.force)
 
@@ -399,7 +400,7 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
     log_info('Total number of unique k-mers: {umers}',
              umers=countgraph.n_unique_kmers())
 
-    if args.savegraph:
+    if args.savegraph is not None:
         log_info('...saving to {name}', name=args.savegraph)
         countgraph.save(args.savegraph)
 

scripts/partition-graph.py

@@ -48,10 +48,8 @@
 import threading
 import textwrap
 import sys
-import gc
-import os.path
 
-from khmer import __version__, load_nodegraph
+from khmer import load_nodegraph
 from khmer.khmer_args import (add_threading_args, sanitize_help,
                               KhmerArgumentParser)
 from khmer.kfile import check_input_files
@@ -79,9 +77,9 @@ def get_parser():
 
     parser.add_argument('basename', help="basename of the input k-mer "
                         "nodegraph  + tagset files")
-    parser.add_argument('--stoptags', '-S', metavar='filename', default='',
+    parser.add_argument('-S', '--stoptags', metavar='filename', default='',
                         help="Use stoptags in this file during partitioning")
-    parser.add_argument('--subset-size', '-s', default=DEFAULT_SUBSET_SIZE,
+    parser.add_argument('-s', '--subset-size', default=DEFAULT_SUBSET_SIZE,
                         type=float, help='Set subset size (usually 1e5-1e6 is '
                         'good)')
     parser.add_argument('--no-big-traverse', action='store_true',

scripts/readstats.py

@@ -49,7 +49,6 @@
 import screed
 import textwrap
 
-from khmer import __version__
 from khmer.khmer_args import sanitize_help, KhmerArgumentParser
 
 

scripts/trim-low-abund.py

@@ -105,11 +105,11 @@ def get_parser():
 
     parser.add_argument('input_filenames', nargs='+')
 
-    parser.add_argument('--cutoff', '-C', type=int,
+    parser.add_argument('-C', '--cutoff', type=int,
                         help='remove k-mers below this abundance',
                         default=DEFAULT_CUTOFF)
 
-    parser.add_argument('--trim-at-coverage', '-Z', '--normalize-to',
+    parser.add_argument('-Z', '--trim-at-coverage', '--normalize-to',
                         type=int,
                         help='trim reads when entire read above this coverage',
                         default=DEFAULT_TRIM_AT_COVERAGE)
@@ -121,7 +121,7 @@ def get_parser():
                         'specify that output should go to STDOUT (the '
                         'terminal)')
 
-    parser.add_argument('--variable-coverage', '-V', action='store_true',
+    parser.add_argument('-V', '--variable-coverage', action='store_true',
                         default=False,
                         help='Only trim low-abundance k-mers from sequences '
                         'that have high coverage.')
@@ -140,8 +140,9 @@ def get_parser():
 
     # expert options
     parser.add_argument('--force', default=False, action='store_true')
-    parser.add_argument('--ignore-pairs', default=False, action='store_true')
-    parser.add_argument('--tempdir', '-T', type=str, default='./',
+    parser.add_argument('--ignore-pairs', default=False, action='store_true',
+                        help='treat all reads as if they were singletons')
+    parser.add_argument('-T', '--tempdir', type=str, default='./',
                         help="Set location of temporary directory for "
                         "second pass")
     add_output_compression_type(parser)

scripts/unique-kmers.py

@@ -102,18 +102,18 @@ def get_parser():
     parser.add_argument('-q', '--quiet', dest='quiet', default=False,
                         action='store_true')
 
-    parser.add_argument('--ksize', '-k', type=int, default=env_ksize,
+    parser.add_argument('-k', '--ksize', type=int, default=env_ksize,
                         help='k-mer size to use')
 
-    parser.add_argument('--error-rate', '-e', type=float, default=0.01,
+    parser.add_argument('-e', '--error-rate', type=float, default=0.01,
                         help='Acceptable error rate')
 
-    parser.add_argument('--report', '-R',
+    parser.add_argument('-R', '--report',
                         metavar='filename', type=argparse.FileType('w'),
                         help='generate informational report and write to'
                         ' filename')
 
-    parser.add_argument('--stream-records', '-S', default=False,
+    parser.add_argument('-S', '--stream-records', default=False,
                         action='store_true',
                         help='write input sequences to STDOUT')