# xmx111/pytom-match-pick architecture

> Architecture diagram of the GitHub repository xmx111/pytom-match-pick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xmx111/pytom-match-pick
- Repository: https://github.com/xmx111/pytom-match-pick

## Overview

##### Project Type and Purpose
- The project is a standalone Python package that performs template matching and related image processing tasks on tomographic data. Its purpose is to accelerate and automate processing in cryo-electron tomography.
- Its command-line interface supports specific operations such as creating templates, building masks, matching templates against tomograms, extracting candidate molecules, calculating ROC curves, and merging star files.

##### File Structure
- Top-level directories include:
- .github – Contains CI/CD workflows (e.g., tests, code coverage, release, and documentation deployment).
- docs – Holds developer documentation, tutorials, FAQs, benchmark examples, images, and scripts for building the website.
- src/pytom_tm – The core source code is encapsulated here with modules such as angles, correlation, entry_points, extract, io, mask, matching, parallel, plotting, template, tmjob, utils, and weights. These modules suggest a modular design where each file implements a distinct piece of functionality.
- tests – The unit tests are grouped here along with sample data (MRC files, star files, etc.) to validate each functionality.
- Build and configuration files (e.g., pyproject.toml, MANIFEST.in, mkdocs.yml) further indicate a structured package setup and documentation build process.

##### Extracting Insights from the README
- The README clearly details required dependencies (miniconda, nvidia-cuda-toolkit) and emphasizes the importance of proper GPU and Cupy installation.
- It lists several command-line scripts (e.g., “pytom_create_template.py”, “pytom_match_template.py”) that serve as entry points to various processing tasks.
- It describes developer and user installation methods and provides guidance on testing and documentation building.

a. Main Components:
- Command-Line Interface (CLI): Represented by the various scripts (template creation, mask creation, matching, extracting candidates, ROC estimation, merging star files). They likely reside in the module “entry_points.py” that offers a unified access point.
- Core Processing Modules: Group modules under functional areas:
- Data I/O: Handled by a dedicated module (io.py) for reading MRC and star files.
- Preprocessing & Masking: Implemented in “mask.py” to prepare regions of interest.
- Template Handling: “template.py” and related modules that generate and manage templates.
- Matching and Scoring: Modules such as “matching.py”, “correlation.py”, and “tmjob.py” drive the template matching algorithms.
- Post-Processing & Analysis: “plotting.py” for visualization and “weights.py” for additional scoring.
- Supporting Utilities: “angles.py”, “parallel.py”, “utils.py” streamline computations and manage parallel processes.
- GPU Acceleration: Cupy is used as a dependency, so include a distinct component representing GPU support and CUDA toolkit integration.
- External Dependencies: Show integration points for CUDA libraries, Conda environment management, and optionally dependencies like matplotlib and seaborn for plotting.
- Testing & CI/CD: Represent the tests directory (with sample input data) and highlight automated tests defined in .github/workflows.

b. Relationships and Interactions:
- Input data (tomograms in .mrc format) flows into I/O modules.
- Processed data then branches into different pipelines such as template creation, mask generation, and matching algorithms.
- Intermediate results (such as correlation outputs) are fed into analysis modules (e.g., for plotting ROC curves).
- The CLI acts as the orchestrator, triggering the appropriate modules based on the command-line invoked.
- GPU routines (via Cupy) should be shown as an accelerator node that interacts with multiple processing modules.

c. Architectural Patterns and Design Principles:
- Modular design: Each functionality (I/O, masking, matching, plotting) is encapsulated in separate modules.
- Separation of concerns: The system separates core computational logic from orchestration (entry points) and from user-interface (CLI commands).
- Extensibility: The clear division allows new algorithms or functionalities to be added with localized changes.
- Testing and Continuous Integration: The integration of CI/CD workflows promote a high-quality, maintainable codebase.

d. Relevant Technologies and Libraries:
- Python with standard library modules
- Cupy for GPU acceleration
- CUDA (installed via nvidia-cuda-toolkit)
- Optional: Matplotlib and Seaborn for plotting and visualization
- Conda for environment management (installation, dependency handling)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    subgraph "User Interface"
        CLI["Command-Line Interface"] 
    end

    %% Data Ingestion
    subgraph "Data Ingestion"
        IO["Data I/O Module"]
    end

    %% Core Processing
    subgraph "Core Processing"
        PM["Preprocessing & Masking"]
        TH["Template Handling"]
        subgraph "Matching & Scoring"
            M["Matching Algorithm"]
            C["Correlation Computations"]
            TJ["Job Management"]
        end
        VP["Post-Processing & Visualization"]
        subgraph "Supporting Utilities"
            ANGLE["Angle Calculations"]
            PAR["Parallel Processing"]
            UTIL["General Utilities"]
            WEIGHTS["Additional Scoring/Weights"]
        end
    end

    %% GPU Acceleration & External Dependencies
    subgraph "GPU Acceleration & External Dependencies"
        GPU["GPU/Cupy Support"]
        EXT["CUDA / External Dependencies"]
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        TEST["Automated Tests"]
        CI["CI/CD Workflows"]
    end

    %% Relationships / Data Flow
    CLI --> IO
    IO --> PM
    IO --> TH
    PM --> M
    TH --> M
    M --> C
    M --> TJ
    M --> VP

    %% Utilities support relationship (dashed)
    ANGLE -.-> M
    PAR -.-> M
    UTIL -.-> M
    WEIGHTS -.-> M

    %% GPU integration with matching modules
    GPU --> M
    GPU --> C
    GPU --> TJ
    EXT --> GPU

    %% CI/CD and Testing feed back to CLI
    CI --> CLI
    TEST --> CLI

    %% Styling classes
    class CLI cliStyle;
    class IO ioStyle;
    class PM procStyle;
    class TH procStyle;
    class M scoreStyle;
    class C scoreStyle;
    class TJ scoreStyle;
    class VP visStyle;
    class ANGLE utilStyle;
    class PAR utilStyle;
    class UTIL utilStyle;
    class WEIGHTS utilStyle;
    class GPU gpuStyle;
    class EXT extStyle;
    class CI cicdStyle;
    class TEST cicdStyle;

    %% Click Events
    click CLI "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/entry_points.py"
    click IO "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/io.py"
    click PM "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/mask.py"
    click TH "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/template.py"
    click M "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/matching.py"
    click C "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/correlation.py"
    click TJ "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/tmjob.py"
    click VP "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/plotting.py"
    click ANGLE "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/angles.py"
    click PAR "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/parallel.py"
    click UTIL "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/utils.py"
    click WEIGHTS "https://github.com/xmx111/pytom-match-pick/blob/main/src/pytom_tm/weights.py"
    click TEST "https://github.com/xmx111/pytom-match-pick/tree/main/tests"
    click CI "https://github.com/xmx111/pytom-match-pick/tree/main/.github/workflows"

    %% Styles
    classDef cliStyle fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef ioStyle fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef procStyle fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef scoreStyle fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef visStyle fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef utilStyle fill:#D3D3D3,stroke:#000,stroke-dasharray: 5 5;
    classDef gpuStyle fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef extStyle fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef cicdStyle fill:#F08080,stroke:#000,stroke-width:2px;
```
