How jhawkey/is_mapper works
Main Components
• Input Components:
– Paired-end read files (Illumina short reads)
– IS query sequences (FASTA format)
– Reference genomes (GenBank format)
• Core Processing Modules (located in the “scripts” directory):
– IS mapping module (ismap.py), which handles initial read mapping to the IS query using BWA.
– Flanking read extraction modules (e.g., read_grouping.py) that identify reads paired to those mapping the IS.
– Secondary mapping modules (mapping_to_query.py, mapping_to_ref.py) that remap extracted flanking reads to either the IS query or the reference genome.
• Data Analysis and Post-Processing:
– Use of external tools for processing mapped reads (SAMtools for filtering; Bedtools to determine coverage and merge close flanking regions).
– Compiled output generation script (compiled_table.py), which merges individual isolate result tables into comprehensive output tables.
• Auxiliary Modules:
– run_commands.py and create_output.py manage workflow orchestration and output formatting.
– ismap_v2_unittests.py indicates a testing strategy (supporting reliability and debugging).
External Dependencies and Integration Layers
• External Bioinformatics tools (BWA, SAMtools, Bedtools, and BLAST+):
– These act as subordinate “engines” that process mapping, filtering, and region merging.
– They are invoked by the Python scripts to perform highly specialized tasks.
• Python3 along with BioPython:
– Forms the core language and bioinformatics library support for parsing sequences and GenBank files.
• Build and Installation Scripts:
– setup.py indicates the packaging and deployment strategy.
– Conda and pip installation instructions show flexibility in deployment.
Data Flow and Interactions
• The user triggers the tool via command-line interface using appropriate flags (for example, “--reads”, “--queries”, “--reference”, and “--output_dir”).
• The initial mapping step (in ismap.py using BWA) aligns reads to the provided IS query.
• The next stage extracts the unmapped paired reads (using SAMtools) and groups them by flanking orientation (left/right), directed by the read_grouping.py module.
• These flanking read groups are separately mapped to the reference genome (using mapping_to_ref.py), after which Bedtools is used to assess read depth and to merge nearby hits.
• The processed mapping data is then formatted into output tables (one per isolate, one per IS query, with subdirectories structured by output_dir) describing IS positions and associated gene features.
• Finally, the compiled_table.py script aggregates individual outputs to create summary tables that capture all IS hits across isolates.