How waymentsteelelab/dyna-1 works
Project Type and Purpose
• Dyna-1 is a research-oriented protein dynamics prediction tool. It takes protein sequence and/or structure as input and predicts the probability of micro-to-millisecond motions per residue.
• The README makes it clear that Dyna-1 leverages pre-trained models (ESM-3 and ESM-2 embeddings) for inference, is used for scientific research, and includes components for visualization (via PyMol) and analysis (via Jupyter notebooks).
File Structure to Extract Main Components
• Top-level directories:
– analysis: Contains Jupyter notebooks that analyze datasets and model outputs.
– assets: Stores images (e.g., for the README) used in documentation.
– colab: Provides Google Colab notebooks to demo/infer using Dyna-1.
– configs: Contains configuration files (e.g., af2.yml, esm2.yml, and esm3.yml) which suggest configurable model settings.
– data: Holds multiple types of datasets (JSON zip files, Excel spreadsheets, CSVs) and dataloader scripts. This clearly shows data ingestion and pre-processing are integral.
– esm: A large folder with submodules (data, layers, models, tokenization, utils, widgets) – essentially encapsulating the ESM (Evolutionary Scale Model) framework and associated utilities. This is used to process sequence/structure data and interface with pre-trained model weights.
– model: Houses the main implementation for Dyna-1 (e.g., model.py, naive_classifier.py, transformer.py) along with a folder for model weights – this forms the core prediction engine.
– scripts: Provides shell scripts to evaluate different configurations or variants of the model.
– Other files (e.g., dyna1.py, dyna1-esm2.py) are direct entry points for inference using different pre-trained weights.
• Additional configuration and utility files (e.g., requirements.txt, utils.py, LICENSE.txt) support deployment and reproducible research.
Design the System Components
A. Data Ingestion & Preprocessing
– Include data sources (datasets in JSON, CSV, Excel, and compressed files in the “data” folder).
– The “data/dataloader.py” and related scripts handle file parsing, splitting, and vocabulary processing.
B. Configuration Management
– The “configs” folder holds YAML files that define model parameters for various run modes (af2, baseline, esm2, esm3).
C. Core Model & Prediction Engine
– The Dyna-1 model code in the “model” directory implements the prediction logic.
– It integrates components from the “esm” folder, such as layers, tokenization, and pre-trained model modules.
D. ESM Framework Integration
– The “esm” directory encompasses:
• Data management (for handling domain-specific inputs),
• Model layers (attention, transformer stacks, etc.),
• Tokenization strategies for sequences and structures,
• SDK/API components (e.g., for integration with HuggingFace and Sagemaker).
– This should be depicted as a unified module that the Dyna-1 engine leverages.
E. Inference Interfaces & Scripts
– Represent the various command-line interfaces (dyna1.py, dyna1-esm2.py) and the “scripts” folder that facilitates evaluation of different configurations.
F. Analysis & Visualization
– Additionally, illustrate the connection to external visualization tools like PyMol (used for putty-rendered structures).
G. External Dependencies & Integration Points
Design Principles and Relationships Between Components
• Clear separation between configuration, data processing, model prediction, and visualization.
• That the inference scripts (dyna1.py and dyna1-esm2.py) serve as entry points that integrate multiple backend modules (esm, model, and data).
• Use connectors to indicate that the “esm” framework provides pre-trained model functionality which is wrapped by the Dyna-1 predictive model.
• That modularity exists via the configuration files allowing the same structure to run different model configurations.