Merge pull request #201 from pachterlab/minor-gget-virus-fixes

Minor gget virus fixes

Author: ferbsx

docs/src/en/updates.md

@@ -1,4 +1,12 @@
 ## ✨ What's new
+**Version ≥ 0.30.2** (Jan 23, 2026):  
+- [`gget virus`](virus.md): Metadata streaming optimization, improved protein filtering, and enhanced error handling
+  - Metadata now streams to disk during fetch to prevent memory exhaustion on large datasets (100,000+ records)
+  - Fixed metadata CSV mapping (camelCase → snake_case) for organism name, host, and collection date
+  - Enhanced protein filtering for segmented viruses with improved FASTA header parsing
+  - Added `annotated=False` option for filtering unannotated sequences
+  - Added progress bars to batched sequence downloads
+
 **Version ≥ 0.30.1** (Jan 22, 2026):  
 - [`gget virus`](virus.md): Improved reliability with enhanced error handling and retry logic
   - Fixed collection date naming bug

docs/src/en/virus.md

@@ -11,7 +11,7 @@ This module was written by [Ferdous Nasri](https://github.com/ferbsx).
 
 **Positional argument**  
 `virus`  
-Virus taxon name (e.g. 'Zika virus'), taxon ID (e.g. 2697049), or accession number (e.g. 'NC\_045512.2').  
+Virus taxon name (e.g. 'Zika virus'), taxon ID (e.g. 2697049), accession number (e.g. 'NC\_045512.2'), space-separated list of accessions (e.g. 'NC\_045512.2 MN908947.3 MT020781.1'), or path to a text file containing accession numbers (one per line, when combined with `--is_accession`).  
 
 **Optional arguments**   
 `-o` `--out`  
@@ -81,17 +81,17 @@ Filter by geographic location of sample collection (e.g. 'USA', 'Asia').
 `--submitter_country`  
 Filter by the country of the sequence submitter.
 
-`--source_database`  
-Filter by source database. One of: 'genbank' or 'refseq'.
-
 _SARS-CoV-2 specific filters_
 
 `--lineage`  
 Filter by SARS-CoV-2 lineage (e.g. 'B.1.1.7', 'P.1').
 
 **Flags**  
 `-a` `--is_accession`  
-Flag to indicate that the `virus` positional argument is an accession number.
+Flag to indicate that the `virus` positional argument is an accession number, space-separated list of accessions, or path to a text file containing accession numbers (one per line). For SARS-CoV-2 and Alphainfluenza cached downloads, supports:
+  - Single accession: `NC_045512.2`
+  - Space-separated list: `NC_045512.2 MN908947.3 MT020781.1`
+  - Text file path: `accessions.txt` (one accession per line)
 
 `--refseq_only`  
 Flag to limit search to RefSeq genomes only (higher quality, curated sequences).
@@ -666,66 +666,6 @@ virus()
   - **Failed GenBank metadata batches**: Accession lists with individual retry URLs
   - All failed operations include exact commands/URLs that can be run manually for retry
 
-## Performance Characteristics
-
-### Scalability
-- **Small datasets** (< 1,000 sequences): Near-instantaneous processing
-- **Medium datasets** (1,000 - 10,000 sequences): Minutes to complete
-- **Large datasets** (> 10,000 sequences): Optimized pagination and filtering
-
-### Memory Usage
-- Streaming processing minimizes memory footprint
-- Metadata cached in memory for filtering operations
-- Large FASTA files processed in chunks
-
-### Network Efficiency
-- Minimal API calls due to server-side filtering
-- Targeted downloads reduce bandwidth usage
-- Automatic retry with exponential backoff
-
-## Error Handling
-
-### API Failures
-- Smart retry strategy with exponential backoff and jitter
-- Server-side error detection with specific guidance:
-  - Timeout handling for large datasets
-  - Geographic filter optimization suggestions
-  - Batch size adjustments for GenBank metadata
-- Connection pooling and session management
-- Detailed error logging with troubleshooting steps
-
-### Data Validation
-- Comprehensive input parameter validation:
-  - Type checking for all parameters
-  - Range validation for numeric values
-  - Date format and range validation
-  - Boolean parameter normalization
-- Sequence integrity verification:
-  - FASTA format validation
-  - Ambiguous character detection
-  - Protein/gene completeness checks
-- Metadata consistency validation:
-  - Required field presence checks
-  - Data type validation
-  - Cross-reference validation
-  - GenBank record validation
-
-### Recovery Mechanisms
-- Automatic temporary file cleanup
-- Partial result preservation:
-  - Intermediate metadata saving
-  - Progressive filtering state saving
-  - GenBank metadata caching
-- Hierarchical fallback strategies:
-  - SARS-CoV-2 optimized packages
-  - Cached data fallback
-  - API-based retrieval fallback
-- Detailed error reporting:
-  - Root cause analysis
-  - Alternative command suggestions
-  - Filter relaxation recommendations
-  - Performance optimization tips
-
 ## Usage Examples
 
 ### Command Line Examples

docs/src/es/updates.md

@@ -1,4 +1,12 @@
 ## ✨ ¡Lo más reciente!  
+**Versión ≥ 0.30.2** (23 de enero de 2026):  
+- [`gget virus`](virus.md): Optimización de streaming de metadatos, filtrado mejorado de proteínas y manejo de errores mejorado
+  - Los metadatos ahora se transmiten al disco durante la búsqueda para evitar el agotamiento de memoria en conjuntos de datos grandes (100.000+ registros)
+  - Se corrigió el mapeo de CSV de metadatos (camelCase → snake_case) para nombre de organismo, host y fecha de recopilación
+  - Filtrado mejorado de proteínas para virus segmentados con análisis mejorado de encabezados FASTA
+  - Se agregó la opción `annotated=False` para filtrar secuencias sin anotar
+  - Se agregaron barras de progreso a las descargas de secuencias en lotes
+
 **Versión ≥ 0.30.0** (19 de enero de 2026):  
 - NUEVOS MÓDULOS:
   - [`gget 8cube`](8cube.md)

docs/src/es/virus.md

@@ -11,7 +11,7 @@ Este módulo fue escrito por [Ferdous Nasri](https://github.com/ferbsx).
 
 **Argumento posicional**  
 `virus`  
-Nombre del taxón del virus (p. ej. 'Zika virus'), ID taxonómico (p. ej. 2697049) o número de acceso (p. ej. 'NC\_045512.2').  
+Nombre del taxón del virus (p. ej. 'Zika virus'), ID taxonómico (p. ej. 2697049), número de acceso (p. ej. 'NC\_045512.2'), lista de accesiones separadas por espacios (p. ej. 'NC\_045512.2 MN908947.3 MT020781.1'), o ruta a un archivo de texto que contiene números de acceso (uno por línea, cuando se combina con `--is_accession`).  
 
 **Argumentos opcionales**   
 `-o` `--out`  
@@ -81,17 +81,17 @@ Filtra por ubicación geográfica de la recolección de la muestra (p. ej. 'USA'
 `--submitter_country`  
 Filtra por el país del remitente de la secuencia.
 
-`--source_database`  
-Filtra por base de datos de origen. Uno de: 'genbank' o 'refseq'.
-
 _Filtros específicos de SARS-CoV-2_
 
 `--lineage`  
 Filtra por linaje de SARS-CoV-2 (p. ej. 'B.1.1.7', 'P.1').
 
 **Banderas**  
 `-a` `--is_accession`  
-Bandera para indicar que el argumento posicional `virus` es un número de acceso.
+Bandera para indicar que el argumento posicional `virus` es un número de acceso, una lista de accesiones separadas por espacios, o una ruta a un archivo de texto que contiene números de acceso (uno por línea). Para descargas en caché de SARS-CoV-2 y Alphainfluenza, soporta:
+  - Acceso único: `NC_045512.2`
+  - Lista separada por espacios: `NC_045512.2 MN908947.3 MT020781.1`
+  - Ruta de archivo de texto: `accessions.txt` (uno por línea)
 
 `--refseq_only`  
 Bandera para limitar la búsqueda solo a genomas RefSeq (secuencias de mayor calidad, curadas).