DOCSEARCHbyAlgolia
Submit Docs

EVcouplings

repository·develop·Indexed 43 days ago

https://github.com/debbiemarkslab/evcouplings

A Python framework (v0.3.0) for evolutionary couplings analysis used to predict protein structure, function, and mutations by analyzing evolutionary sequence covariation. It includes modules for sequence alignment (evcouplings.align), folding analysis (evcouplings.fold), mutation calculations (evcouplings.mutate), and visualization (evcouplings.visualize), as well as a CLI for running computational pipelines.

Tokens
14.2K
Snippets
39
Records
59
Agent score
55%

What's inside EVcouplings

  1. Overview of the evcouplings.visualize package

    develop

    The evcouplings.visualize package provides visualization utilities for EVcouplings data. It is organized into several specialized modules depending on the type of data you wish to visualize:

    • evcouplings.visualize.misc: Miscellaneous visualization utilities.
    • evcouplings.visualize.mutations: Tools for visualizing mutations.
    • evcouplings.visualize.pairs: Tools for visualizing residue pairs.
    • evcouplings.visualize.parameters: Tools for visualizing parameters.
    • evcouplings.visualize.pymol: Integration with PyMOL for structural visualization.

  2. Overview of the evcouplings.align package

    develop

    The evcouplings.align package provides tools for sequence alignment and protein family analysis within the EVcouplings ecosystem. It is organized into several specialized modules:

    • evcouplings.align.alignment: Core alignment functionality.
    • evcouplings.align.pfam: Tools for interacting with or utilizing Pfam protein families.
    • evcouplings.align.protocol: Implementation of specific alignment protocols.
    • evcouplings.align.tools: General utility tools for alignment tasks.

  3. Overview of EVcouplings modules

    develop

    EVcouplings is organized into several functional modules for analyzing evolutionary couplings, protein folding, and structural alignment:

    • Alignment: Tools for sequence alignment (evcouplings.align).
    • Couplings Analysis: Core analysis tools including comparison (evcouplings.compare), complex analysis (evcouplings.complex), coupling identification (evcouplings.couplings), and mutation analysis (evcouplings.mutate).
    • Folding Analysis: Tools for analyzing protein folding (evcouplings.fold).
    • Visualization: Modules for visualizing results (evcouplings.visualize).
    • Utilities: General helper functions (evcouplings.utils).

  4. Explore the evcouplings.fold package modules

    develop

    The evcouplings.fold package provides a suite of modules for handling protein folding and coupling data. The package is organized into several functional modules:

    • evcouplings.fold.cns: Likely handles CNS (Crystallography & NMR System) related data or interfaces.
    • evcouplings.fold.filter: Provides tools for filtering coupling or folding data.
    • evcouplings.fold.protocol: Manages folding protocols or workflow definitions.
    • evcouplings.fold.ranking: Contains logic for ranking results or coupling strengths.
    • evcouplings.fold.restraints: Handles the definition and application of structural restraints.
    • evcouplings.fold.tools: Contains general utility functions for the folding workflow.

  5. Use the evcouplings.mutate package

    develop

    The evcouplings.mutate package provides tools for mutation-related calculations and protocol definitions. It is divided into two primary modules:

    1. evcouplings.mutate.calculations: Contains the core computational logic for mutation analysis.
    2. evcouplings.mutate.protocol: Defines the protocols and interfaces used for mutation data handling and communication.

    Refer to the specific module documentation for detailed API signatures and function behaviors.

  6. Install optional external software tools

    develop

    The following tools are optional and are only required if you need specific functionalities in the computational pipeline (primarily for the fold stage).

    ToolPurposeRequirement
    HHsuiteUses hhfilter to filter sequence alignmentsRequired only if alignment filtering is needed
    CNSsolve 1.21Computes 3D structure models from coupled residue pairsRequired for the fold stage
    PSIPREDSecondary structure predictionRequired for the fold stage if not supplying your own predictions
    maxclusterCompares predicted 3D models to experimental structuresRequired for the fold stage

    Note on CNSsolve: You do not need to run the cns_solve_env shell script. EVcouplings manages environment variables internally. You only need to provide the path to the cns binary in your job configuration file (e.g., cns_solve_1.21/intel-x86_64bit-linux/bin/cns).

  7. Set up sequence and structure mapping databases

    develop

    EVcouplings requires sequence databases for alignment generation and structure mapping information for 3D structure comparison.

    Automatic Setup

    You can automatically download UniProt (SwissProt/TrEMBL), UniRef100, and UniRef90 databases and generate SIFTS-based structure mapping tables using the evcouplings_dbupdate command-line tool.

    evcouplings_dbupdate --help

    Manual/Custom Setup

    • Custom Sequence Databases: You can use any FASTA format database. Define the path in the databases section and set it as the input in the alignment section of your job configuration file.
    • Structure Databases: PDB structures are automatically fetched in MMTF format per job. To pre-download them, set the pdb_mmtf_dir configuration parameter.
    • Mapping Files: You can point sifts_mapping_table and sifts_sequence_db to existing file paths in your config. If they don't exist, EVcouplings will attempt to fetch and create them automatically during the first run.
    evcouplings_dbupdate --help

  8. Install the EVcouplings Python package

    develop

    To use EVcouplings as a library, install the Python package via pip. The project requires Python >= 3.10.

    Install latest version from PyPI:

    pip install evcouplings

    Install latest development version from GitHub:

    pip install https://github.com/debbiemarkslab/EVcouplings/archive/develop.zip

    Update development version:

    pip install -U --no-deps https://github.com/debbiemarkslab/EVcouplings/archive/develop.zip
    pip install evcouplings

  9. Access EVcouplings tutorials and documentation

    develop

    For practical guidance on using the tool, refer to the following resources:

    • Jupyter Notebooks: Located in the notebooks/ subdirectory of the repository. They provide guides on:
      • Editing configuration files
      • Running jobs
      • Using EVcouplings as a Python library
    • API Documentation: Detailed source code documentation is available at readthedocs.

  10. Install required external software tools

    develop

    If you intend to run the full evcouplings application (alignment generation, model parameter inference, structure prediction, etc.), you must install the following required tools and provide their paths in your job configuration file.

    plmc (Required)

    Used for inferring undirected statistical models from sequence variation.

    jackhmmer (Required)

    Used for HMM-based searches.

    make all-openmp32

  11. Available EVcouplings pipelines

    develop

    The pipeline execution engine supports two primary workflow types defined in the PIPELINES dictionary:

    1. protein_monomer: A standard sequence of stages for single protein analysis:

      • align
      • couplings
      • compare
      • mutate
      • fold

    2. protein_complex: A workflow designed for protein complexes, including an initial concatenation step and dual alignment stages:

      • align_1 (uses first_ prefix)
      • align_2 (uses second_ prefix)
      • concatenate
      • couplings
      • compare
      • mutate
      • fold

  12. Understand EVcouplings pipeline stages

    develop

    The pipeline is divided into sequential stages. You can control which stages run by commenting them out in the stages section of your configuration file. Stages must be run in order.

    Available Stages:

    1. align: Creates/reads sequence alignments and pre-processes them.
    2. couplings: Calculates evolutionary couplings and fits statistical scoring models.
    3. compare: Compares couplings against structures and calculates precision.
    4. mutate: Generates and visualizes mutation effect matrices.
    5. fold: Generates folded models using couplings as input.

    Restarting Jobs: To restart from an arbitrary stage (e.g., to re-run compare with new parameters), use the same prefix and comment out the stages that have already successfully completed.

    Warning: Re-running a stage will overwrite its previous results. Use the --yolo flag in the CLI to allow this.