Merge pull request #1797: filter: Update notes around --sequence-index

Author: victorlin

CHANGES.md

@@ -2,6 +2,11 @@
 
 ## __NEXT__
 
+### Bug fixes
+
+* filter: Removed the note that appeared in output when running with `--sequences` and without `--sequence-index`. The help text of both options has been updated to clarify the relationship between the two. [#1797][] (@victorlin)
+
+[#1797]: https://github.com/nextstrain/augur/pull/1797
 
 ## 30.0.0 (15 April 2025)
 

augur/filter/__init__.py

@@ -18,8 +18,8 @@ def register_arguments(parser):
     """
     input_group = parser.add_argument_group("inputs", "metadata and sequences to be filtered")
     input_group.add_argument('--metadata', required=True, metavar="FILE", help="sequence metadata")
-    input_group.add_argument('--sequences', '-s', help="sequences in FASTA or VCF format")
-    input_group.add_argument('--sequence-index', help="sequence composition report generated by augur index. If not provided, an index will be created on the fly.")
+    input_group.add_argument('--sequences', '-s', help="sequences in FASTA or VCF format. For large inputs, consider using --sequence-index in addition to this option.")
+    input_group.add_argument('--sequence-index', help="sequence composition report generated by augur index. If not provided, an index will be created on the fly. This should be generated from the same file as --sequences.")
     input_group.add_argument('--metadata-chunk-size', type=int, default=100000, help="maximum number of metadata records to read into memory at a time. Increasing this number can speed up filtering at the cost of more memory used.")
     input_group.add_argument('--metadata-id-columns', default=DEFAULT_ID_COLUMNS, nargs="+", action=ExtendOverwriteDefault, help="names of possible metadata columns containing identifier information, ordered by priority. Only one ID column will be inferred.")
     input_group.add_argument('--metadata-delimiters', default=DEFAULT_DELIMITERS, nargs="+", action=ExtendOverwriteDefault, help="delimiters to accept when reading a metadata file. Only one delimiter will be inferred.")

augur/filter/_run.py

@@ -46,18 +46,12 @@ def run(args):
         build_sequence_index = True
 
     if build_sequence_index:
-        # Generate the sequence index on the fly, for backwards compatibility
-        # with older workflows that don't generate the index ahead of time.
-        # Create a temporary index using a random filename to avoid collisions
-        # between multiple filter commands.
+        # Generate the sequence index on the fly for workflows that don't do
+        # this separately. Create a temporary index using a random filename to
+        # avoid collisions between multiple filter commands.
         with NamedTemporaryFile(delete=False) as sequence_index_file:
             sequence_index_path = sequence_index_file.name
 
-        print_err(
-            "Note: You did not provide a sequence index, so Augur will generate one.",
-            "You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`."
-        )
-
         if is_vcf:
             index_vcf(args.sequences, sequence_index_path)
         else:

tests/functional/filter/cram/filter-deprecated-options.t

@@ -26,7 +26,6 @@ Create files
   >   --sequences sequences.fasta \
   >   --output filtered.fasta
   WARNING: --output is deprecated. Use --output-sequences instead.
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   1 strain was dropped during filtering
   	1 had no metadata
   2 strains passed all filters
@@ -44,7 +43,6 @@ Create files
   >   --sequences sequences.fasta \
   >   -o filtered.fasta
   WARNING: -o is deprecated. Use --output-sequences instead.
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   1 strain was dropped during filtering
   	1 had no metadata
   2 strains passed all filters

tests/functional/filter/cram/filter-duplicates-error.t

@@ -67,7 +67,6 @@ Error on duplicates in sequences.
   >   --metadata metadata.tsv \
   >   --sequences sequences.fasta \
   >   --output-sequences sequences-filtered.fasta
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   ERROR: The following strains are duplicated in 'sequences.fasta':
   a
   c
@@ -79,7 +78,6 @@ Error even if the corresponding output is not used.
   >   --metadata metadata.tsv \
   >   --sequences sequences.fasta \
   >   --output-strains filtered.txt
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   ERROR: The following strains are duplicated in 'sequences.fasta':
   a
   c

tests/functional/filter/cram/filter-mismatched-sequences-error.t

@@ -12,7 +12,6 @@ This should produce no results because the intersection of metadata and sequence
   >  --min-length 4 \
   >  --max-date 2020-01-30 \
   >  --output-strains filtered_strains.txt > /dev/null
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   13 strains were dropped during filtering
   	1 had no metadata
   	12 had no sequence data
@@ -29,7 +28,6 @@ Repeat with sequence and strain outputs. We should get the same results.
   >  --max-date 2020-01-30 \
   >  --output-strains filtered_strains.txt \
   >  --output-sequences filtered.fasta > /dev/null
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   13 strains were dropped during filtering
   	1 had no metadata
   	12 had no sequence data
@@ -48,7 +46,6 @@ Since we expect metadata to be filtered by presence of strains in input sequence
   >  --sequences dummy.fasta \
   >  --metadata "$TESTDIR/../data/metadata.tsv" \
   >  --output-strains filtered_strains.txt > /dev/null
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   13 strains were dropped during filtering
   	1 had no metadata
   	12 had no sequence data

tests/functional/filter/cram/filter-sequences-vcf.t

@@ -10,7 +10,6 @@ Filter TB strains from VCF and save as a list of filtered strains.
   >  --min-date 2012 \
   >  --output-sequences filtered.vcf \
   >  --output-strains filtered_strains.txt > /dev/null
-  Note: You did not provide a sequence index, so Augur will generate one. You can generate your own index ahead of time with `augur index` and pass it with `augur filter --sequence-index`.
   162 strains were dropped during filtering
   	155 had no sequence data
   	7 were dropped because they were earlier than 2012.0 or missing a date