How cryotud/locscale works
Project type and purpose
• LocScale-2.0 is an open-source Python-based map-optimization program for cryo-EM data.
• It provides a command-line interface (CLI), orchestrates preprocessing, invokes CPU/GPU neural-net modules (EMmerNet), wraps Fortran/C libraries (symmetry, map utilities), and optionally calls external executables (REFMAC5).
File structure
Top-level directories & files:
• locscale/main.py – CLI entrypoint.
• config.py – global settings.
• locscale/automate/… – helper scripts and orchestration tools.
• locscale/preprocessing/… – pipeline definition, data validation, pseudomodel generation.
• locscale/emmernet/… – deep-learning-based map optimization.
• locscale/include/… – wrapped Fortran/Python libraries for confidence mapping, symmetry, EMmer, pdb handling.
• locscale/utils/… – I/O, math, plotting, file-tools.
• locscale/tests/… – unit and integration tests.
• docs/, mkdocs.yml – documentation infrastructure.
README for insights
• Confirms the four main modes: feature-enhanced maps, hybrid sharpening, model-free sharpening, legacy mode.
• Mentions the external dependency REFMAC5 (must be on PATH).
• Advises GPU usage for EMmerNet.
Main components & how they interact
a. CLI Layer (locscale/main.py)
• Parses user inputs, mode selection, file paths, config.
b. Configuration Module (config.py)
• Reads environment variables, default parameters, paths to external executables (e.g., refmac5).
c. Orchestration / Automation (locscale/automate)
• Builds & sequences tasks: preprocessing → map optimization → postprocessing.
d. Preprocessing Pipeline (locscale/preprocessing)
• /model input validation
• Generation of pseudomodels (if needed)
• Data preparation for EMmerNet or confidence maps
e. Core Processing Engines
• EMmerNet Module (locscale/emmernet)
– GPU/CPU routines for neural network-based sharpening.
• Confidence–Map Utilities (locscale/include/confidenceMapUtil)
– Python wrappers around FDRutil, locscaleUtil, mapUtil.
• Symmetry Routines (locscale/include/symmetry_emda)
– Fortran/C code for point-group operations.
• EMmer Wrappers (locscale/include/emmer)
– NDImage & PDB utilities from the EMmer library.
f. External Executable
• REFMAC5
– Invoked for model-based and hybrid sharpening.
g. Utilities (locscale/utils)
• File I/O, mathematical tools, plotting, process launching.
h. Tests (locscale/tests)
• Validate each component in isolation and end-to-end.
Architectural patterns & design principles
• Pipeline/Orchestrator pattern – tasks flow in stages.
• Modular subpackages for each functional area (single responsibility).
• Wrapping of native Fortran/C code behind Python APIs.
• Plugin-style modes (feature enhanced, hybrid, model-free) selected by CLI flags.
• Clear separation of CLI, core logic, and external dependencies.
Essential elements
• Clear component names (e.g., “Preprocessing Pipeline”).
• Callouts for key configuration (e.g., REFMAC5_PATH in config.py).