# jhawkey/is_mapper architecture

> Architecture diagram of the GitHub repository jhawkey/is_mapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jhawkey/is_mapper
- Repository: https://github.com/jhawkey/is_mapper

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Input Layer"
        I1["Paired-end Reads Input"]:::input
        I2["IS Query Input"]:::input
        I3["Reference Genome Input"]:::input
    end

    subgraph "Processing Layer"
        P1["ISM Mapping Module"]:::processing
        P2["Flanking Read Extraction"]:::processing
        subgraph "Secondary Mapping"
            P3A["Secondary Mapping to Query"]:::processing
            P3B["Secondary Mapping to Reference"]:::processing
        end
    end

    subgraph "Output Generation"
        O1["Output Table Generation"]:::output
        subgraph "Workflow Management"
            O2["Workflow Orchestration"]:::output
            O3["Output Formatter"]:::output
        end
    end

    T1["Testing Module (Unit Tests)"]:::testing

    subgraph "External Tools"
        E1["BWA"]:::external
        E2["SAMtools"]:::external
        E3["Bedtools"]:::external
        E4["BLAST+"]:::external
    end

    %% Data Flow Connections
    I1 -->|"inputs"| P1
    I2 -->|"ISQuery"| P1
    P1 -->|"BWA_alignment"| E1
    P1 -->|"aligned_reads"| P2
    P2 -->|"SAMtools_filtering"| E2
    P2 -->|"extracted_flanks"| P3A
    P2 -->|"extracted_flanks"| P3B
    I3 -->|"reference_genome"| P3B
    P3B -->|"Bedtools_merging"| E3
    P3A -->|"BLAST+_check"| E4
    P3A -->|"mapping_results"| O1
    P3B -->|"mapping_results"| O1
    O1 -->|"aggregate_tables"| O2
    O2 --> O3

    %% Testing Integration
    T1 ---|"tests"| P1
    T1 ---|"tests"| P2

    %% Click Events
    click I2 "https://github.com/jhawkey/is_mapper/blob/master/test/inputs/ISSsu3.fasta"
    click I3 "https://github.com/jhawkey/is_mapper/blob/master/test/inputs/S_suis_P17.gbk"
    click P1 "https://github.com/jhawkey/is_mapper/blob/master/scripts/ismap.py"
    click P2 "https://github.com/jhawkey/is_mapper/blob/master/scripts/read_grouping.py"
    click P3A "https://github.com/jhawkey/is_mapper/blob/master/scripts/mapping_to_query.py"
    click P3B "https://github.com/jhawkey/is_mapper/blob/master/scripts/mapping_to_ref.py"
    click O1 "https://github.com/jhawkey/is_mapper/blob/master/scripts/compiled_table.py"
    click O2 "https://github.com/jhawkey/is_mapper/blob/master/scripts/run_commands.py"
    click O3 "https://github.com/jhawkey/is_mapper/blob/master/scripts/create_output.py"
    click T1 "https://github.com/jhawkey/is_mapper/blob/master/scripts/ismap_v2_unittests.py"

    %% Styles
    classDef input fill:#FAD,stroke:#333,stroke-width:2px;
    classDef processing fill:#BBF,stroke:#333,stroke-width:2px;
    classDef external fill:#FDD,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5;
    classDef output fill:#DFD,stroke:#333,stroke-width:2px;
    classDef testing fill:#DDD,stroke:#333,stroke-width:2px,stroke-dasharray: 2,2;
```
