### Install Sphinx Dependencies

Source: https://github.com/debbiemarkslab/evcouplings/wiki/Automatic-Documentation

Required packages for building the documentation locally.

```bash
pip install sphinx
```

```bash
pip install sphinx_rtd_theme
```

```bash
pip install sphinxcontrib-napoleon
```

--------------------------------

### Get Help for evcouplings Command

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/running_jobs.ipynb

Run this command to view all available command-line arguments for the main evcouplings application.

```bash
evcouplings --help
```

--------------------------------

### Install EVcouplings via pip

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/README.md

Commands to install the latest stable or development versions of the EVcouplings package.

```bash
pip install evcouplings
```

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

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

--------------------------------

### evcouplings.fold.tools.run_cns

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.fold.html

Runs CNSsolve 1.21, simplifying the process by not requiring manual environment setup.

```APIDOC
## run_cns

### Description
Run CNSsolve 1.21 (without worrying about environment setup).

### Method
Not applicable (Python function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **inp_script** (str, optional) - Path to CNS input script.
* **inp_file** (str, optional) - Path to CNS input file.
* **log_file** (str, optional) - Path to CNS log file.
* **binary** (str, optional, default: 'cns') - The CNSsolve binary to execute.

### Request Example
```python
# Example usage (conceptual):
# from evcouplings.fold import tools
# 
# tools.run_cns(
#     inp_script="path/to/my.inp",
#     inp_file="path/to/my.dat",
#     log_file="cns.log"
# )
```

### Response
#### Success Response (200)
This function executes the CNSsolve command and does not return a specific value, but its success is indicated by the absence of errors during execution and the creation of output files as specified by the CNS input.

#### Response Example
(No direct response, output is typically in log files or generated structures.)
```

--------------------------------

### evcouplings.utils.database.ComputeJob.time_started

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/genindex.html

The time when a compute job started.

```APIDOC
## GET /api/evcouplings/utils/database/ComputeJob/time_started

### Description
Gets the start time of a ComputeJob.

### Method
GET

### Endpoint
/api/evcouplings/utils/database/ComputeJob/time_started

### Parameters
None

### Response
#### Success Response (200)
- **time_started** (string) - The start time in ISO format.

#### Response Example
```json
{
  "time_started": "2023-10-27T09:00:00Z"
}
```
```

--------------------------------

### Run EVcouplings with Options and Overrides

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/running_jobs.ipynb

Execute the evcouplings pipeline with specified options, overriding configuration file settings. This example demonstrates running with different bitscore thresholds for a protein.

```bash
evcouplings -P output/RASH_HUMAN -p RASH_HUMAN -b "0.1, 0.2, 0.3, 0.4, 0.5, 0.6" sample_config.txt
```

--------------------------------

### run_cns

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/fold/tools.html

Executes CNSsolve 1.21 with the specified input script or file, handling environment setup automatically.

```APIDOC
## run_cns

### Description
Runs CNSsolve 1.21. The user is responsible for verifying output products as paths are determined by the .inp scripts.

### Parameters
- **inp_script** (str) - Optional - CNS ".inp" input script commands.
- **inp_file** (str) - Optional - Path to .inp input script file. Overrides inp_script.
- **log_file** (str) - Optional - Path to save CNS stdout output.
- **binary** (str) - Optional - Absolute path of CNS binary (default: "cns").

### Errors
- **ExternalToolError**: If call to CNS fails.
- **InvalidParameterError**: If neither inp_script nor inp_file is provided.
```

--------------------------------

### Command Line App Entry Point

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/pipeline.html

Sets up the command-line interface for the EVcouplings pipeline using `click`. It takes a configuration file as an argument, runs the pipeline using the `run` function, and prints the output configuration to stdout.

```python
CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])

@click.command(context_settings=CONTEXT_SETTINGS)
@click.argument('config')
def app(**kwargs):
    """
    Command line app entry point
    """
    # execute configuration file
    outcfg = run(**kwargs)

    # print final result configuration to stdout
    print(outcfg)

if __name__ == '__main__':
    app()
```

--------------------------------

### Build the project

Source: https://github.com/debbiemarkslab/evcouplings/wiki/Pull-Request-Checklist

Command to verify that the project builds correctly.

```bash
python setup.py sdist
```

--------------------------------

### Access evcouplings_dbupdate help

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/README.md

Command to view help documentation for the database update utility.

```bash
evcouplings_dbupdate --help
```

--------------------------------

### evcouplings.utils.system.temp

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/genindex.html

Gets the temporary directory path.

```APIDOC
## GET /api/evcouplings/utils/system/temp

### Description
Gets the path to the system's temporary directory.

### Method
GET

### Endpoint
/api/evcouplings/utils/system/temp

### Parameters
None

### Response
#### Success Response (200)
- **temp_dir** (string) - The path to the temporary directory.

#### Response Example
```json
{
  "temp_dir": "/tmp"
}
```
```

--------------------------------

### Run Protocol Entry Point

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/compare/protocol.html

The entry point for running the comparison protocol with provided keyword arguments.

```python
def run(**kwargs):
```

--------------------------------

### evcouplings.utils.batch.SlurmSubmitter.submit_command

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/genindex.html

Gets the submit command for SlurmSubmitter.

```APIDOC
## GET /api/evcouplings/utils/batch/SlurmSubmitter/submit_command

### Description
Gets the submit command for SlurmSubmitter.

### Method
GET

### Endpoint
/api/evcouplings/utils/batch/SlurmSubmitter/submit_command

### Parameters
None

### Response
#### Success Response (200)
- **command** (string) - The submit command.

#### Response Example
```json
{
  "command": "sbatch"
}
```
```

--------------------------------

### Generate HTML Documentation

Source: https://github.com/debbiemarkslab/evcouplings/wiki/Automatic-Documentation

Commands to navigate to the documentation directory and build the HTML output.

```bash
cd ./docs
```

```bash
make clean html
```

--------------------------------

### evcouplings.utils.batch.LSFSubmitter.submit_command

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/genindex.html

Gets the submit command for LSFSubmitter.

```APIDOC
## GET /api/evcouplings/utils/batch/LSFSubmitter/submit_command

### Description
Gets the submit command for LSFSubmitter.

### Method
GET

### Endpoint
/api/evcouplings/utils/batch/LSFSubmitter/submit_command

### Parameters
None

### Response
#### Success Response (200)
- **command** (string) - The submit command.

#### Response Example
```json
{
  "command": "bsub"
}
```
```

--------------------------------

### run

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/pipeline.html

Executes the EVcouplings pipeline from a configuration file.

```APIDOC
## run

### Description
Executes the EVcouplings pipeline from a configuration file in single-thread mode.

### Parameters
- **kwargs** (dict) - Required - Arguments including the 'config' file path.
```

--------------------------------

### evcouplings.utils.batch.AClusterSubmitter.submit_command

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/genindex.html

Gets the submit command for AClusterSubmitter.

```APIDOC
## GET /api/evcouplings/utils/batch/AClusterSubmitter/submit_command

### Description
Gets the submit command for AClusterSubmitter.

### Method
GET

### Endpoint
/api/evcouplings/utils/batch/AClusterSubmitter/submit_command

### Parameters
None

### Response
#### Success Response (200)
- **command** (string) - The submit command.

#### Response Example
```json
{
  "command": "sbatch"
}
```
```

--------------------------------

### GET /monitor

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/batch.html

Monitors the status of a command.

```APIDOC
## GET /monitor

### Description
Queries the status of a specific command via the broker.

### Method
GET

### Parameters
#### Query Parameters
- **command** (Command) - Required - The command object to monitor.

### Response
#### Success Response (200)
- **status** (EStatus) - The current status of the command.
```

--------------------------------

### GET /seq

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.couplings.html

Access target sequence of the model.

```APIDOC
## GET /seq

### Description
Access target sequence of model.

### Method
GET

### Parameters
#### Query Parameters
- **i** (Iterable(int) or int) - Optional - Position(s) for which symbol should be retrieved.

### Response
#### Success Response (200)
- **result** (Iterable(char) or char) - Sequence symbols.
```

--------------------------------

### GET /mn

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.couplings.html

Maps model numbering to internal numbering.

```APIDOC
## GET /mn

### Description
Map model numbering to internal numbering.

### Method
GET

### Parameters
#### Query Parameters
- **i** (Iterable(int) or int) - Optional - Position(s) to be mapped from model numbering space into internal numbering space.

### Response
#### Success Response (200)
- **result** (Iterable(int) or int) - Remapped position(s).
```

--------------------------------

### Create Directory Subtree

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/system.html

Creates a directory subtree. Use `exist_ok=True` to avoid errors if the directory already exists.

```python
os.makedirs(directories, exist_ok=True)
```

--------------------------------

### Alignment Class Initialization

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/align/alignment.html

Demonstrates how to initialize an Alignment object from different file formats like FASTA, Stockholm, and A3M.

```APIDOC
## Alignment Initialization

### Description
Initializes an Alignment object by reading sequence data from various formats.

### Method
`Alignment.from_dict(seqs, **kwargs)`

### Parameters
#### Request Body
- **seqs** (dict) - A dictionary where keys are sequence IDs and values are sequences.
- **format** (str) - The format of the input sequence data (e.g., 'fasta', 'stockholm', 'a3m').
- **fileobj** (file-like object) - The file object to read from.
- **a3m_inserts** (bool, optional) - Whether to include inserts when reading A3M format.
- **read_annotation** (bool, optional) - Whether to read annotation from Stockholm format.

### Request Example
```python
# Example for FASTA format
with open('sequences.fasta', 'r') as f:
    alignment = Alignment.from_dict(fileobj=f, format='fasta')

# Example for Stockholm format
with open('alignment.stockholm', 'r') as f:
    alignment = Alignment.from_dict(fileobj=f, format='stockholm', read_annotation=True)

# Example for A3M format
with open('alignment.a3m', 'r') as f:
    alignment = Alignment.from_dict(fileobj=f, format='a3m', a3m_inserts=True)
```

### Response
#### Success Response (200)
- **Alignment** (object) - An initialized Alignment object.

#### Response Example
```json
{
  "message": "Alignment object created successfully"
}
```
```

--------------------------------

### Chain.filter_atoms

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.compare.html

Filters coordinates of a PDB chain, for example to compute C_alpha-C_alpha distances.

```APIDOC
## Chain.filter_atoms

### Description
Filter coordinates of chain, e.g. to compute C_alpha-C_alpha distances.

### Parameters
#### Query Parameters
- **atom_name** (str or list-like) - Optional - Name(s) of atoms to keep (default: "CA")

### Response
- **Chain** - Chain containing only filtered atoms (and those residues that have such an atom)
```

--------------------------------

### ScalarObjectAttributeImpl Get All Pending

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/sqlalchemy/orm/attributes.html

Fetches all pending and committed states for a scalar-holding instrumented attribute.

```python
def get_all_pending(self, state, dict_, passive=PASSIVE_NO_INITIALIZE):
        if self.key in dict_:
            current = dict_[self.key]
        elif passive & CALLABLES_OK:
            current = self.get(state, dict_, passive=passive)
        else:
            return []

        # can't use __hash__(), can't use __eq__() here
        if current is not None and \
                current is not PASSIVE_NO_RESULT and \
                current is not NEVER_SET:
            ret = [(instance_state(current), current)]
        else:
            ret = [(None, None)]

        if self.key in state.committed_state:
            original = state.committed_state[self.key]
            if original is not None and \
                    original is not PASSIVE_NO_RESULT and \
                    original is not NEVER_SET and \
                    original is not current:

                ret.append((instance_state(original), original))
        return ret
```

--------------------------------

### POST /pdb/from_file

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/compare/pdb.html

Initializes a PDB structure from a local MMTF file.

```APIDOC
## POST /pdb/from_file

### Description
Initialize structure from MMTF file.

### Parameters
#### Request Body
- **filename** (str) - Required - Path of MMTF file

### Response
#### Success Response (200)
- **PDB** (object) - Initialized PDB structure
```

--------------------------------

### GET /tilde_fields

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/couplings/mean_field.html

Computes the h_tilde fields for a two-site model given two positions.

```APIDOC
## GET /tilde_fields

### Description
Compute h_tilde fields of the two-site model for specified positions.

### Parameters
#### Query Parameters
- **i** (int) - Required - First position.
- **j** (int) - Required - Second position.

### Response
#### Success Response (200)
- **h_tilde_i** (np.array) - h_tilde fields of position i (size 1 x num_symbols)
- **h_tilde_j** (np.array) - h_tilde fields of position j (size 1 x num_symbols)
```

--------------------------------

### Run alignment protocol entry point

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/align/protocol.html

Main entry point for running an alignment protocol, validating the requested protocol against the registry.

```python
def run(**kwargs):
    """
    Run alignment protocol to generate multiple sequence
    alignment from input sequence.

    Parameters
    ----------
    Mandatory kwargs arguments:
        protocol: Alignment protocol to run
        prefix: Output prefix for all generated files

    Optional:

    Returns
    -------
    Alignment
    Dictionary with results of stage in following fields (in brackets - not returned by all protocols):

        * alignment_file
        * [raw_alignment_file]
        * statistics_file
        * target_sequence_file
        * sequence_file
        * [annotation_file]
        * frequencies_file
        * identities_file
        * [hittable_file]
        * focus_mode
        * focus_sequence
        * segments
    """
    check_required(kwargs, ["protocol"])

    if kwargs["protocol"] not in PROTOCOLS:
        raise InvalidParameterError(
            "Invalid protocol selection: " +
            "{}. Valid protocols are: {}".format(
                kwargs["protocol"], ", ".join(PROTOCOLS.keys())
            )
        )

    return PROTOCOLS[kwargs["protocol"]](**kwargs)
```

--------------------------------

### Execute Pipeline Summary CLI

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/summarize.html

Command-line interface for running summary statistics on specified pipelines using Click.

```python
PIPELINE_TO_SUMMARIZER = {
    "protein_monomer": protein_monomer,
    "protein_complex": protein_complex,
}

@click.command(context_settings=CONTEXT_SETTINGS)
# run settings
@click.argument('pipeline', nargs=1, required=True)
@click.argument('prefix', nargs=1, required=True)
@click.argument('configs', nargs=-1)
def run(**kwargs):
    """
    Create summary statistics for evcouplings pipeline runs
    """
    try:
        summarizer = PIPELINE_TO_SUMMARIZER[kwargs["pipeline"]]
    except KeyError:
        raise InvalidParameterError(
            "Not a valid pipeline, valid selections are: {}".format(
                ",".join(PIPELINE_TO_SUMMARIZER.keys())
            )
        )

    summarizer(kwargs["prefix"], kwargs["configs"])

if __name__ == '__main__':
    run()
```

--------------------------------

### Create and Submit Job Command

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/app.html

Prepares and submits individual jobs, setting their status to pending and creating a submission command with specified resources and environment configurations. The command is then submitted using a Submitter instance.

```python
# create submitter from global (pre-unrolling) configuration
submitter = utils.SubmitterFactory(
    global_config["environment"]["engine"],
    db_path=out_prefix + "_job_database.txt"
)

# collect individual submitted jobs here
commands = []

# prepare individual jobs for submission
for job, job_cfg in configs.items():
    job_prefix = job_cfg["global"]["prefix"]
    job_cfg_file = CONFIG_NAME.format(job)

    # set job status in database to pending
    pipeline.update_job_status(job_cfg, status=database.EStatus.PEND)

    # create submission command
    env = job_cfg["environment"]
    cmd = utils.Command(
        [
            "{} {}".format(cmd_base, job_cfg_file),
            summ_cmd
        ],
        name=job_prefix,
        environment=env["configuration"],
        workdir=workdir,
        resources={
            utils.EResource.queue: env["queue"],
            utils.EResource.time: env["time"],
            utils.EResource.mem: env["memory"],
            utils.EResource.nodes: env["cores"],
            utils.EResource.out: job_prefix + "_stdout.log",
            utils.EResource.error: job_prefix + "_stderr.log",
        }
    )

    # store job for later dependency creation
    commands.append(cmd)

    # finally, submit job
    submitter.submit(cmd)

# submit final summarizer
# (hold for now - summarizer is run after each subjob finishes)

# wait for all runs to finish (but only if blocking)
submitter.join()
```

--------------------------------

### Access Model Alphabet

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/model_parameters_mutation_effects.ipynb

Get the set of amino acid symbols (alphabet) used in the CouplingsModel.

```python
# alphabet
print(c.alphabet)
```

--------------------------------

### GET /pdb/get_chain

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/compare/pdb.html

Extracts residue information and atom coordinates for a given chain in the PDB structure.

```APIDOC
## GET /pdb/get_chain

### Description
Extract residue information and atom coordinates for a given chain in PDB structure.

### Parameters
#### Query Parameters
- **chain** (str) - Required - Name of chain to be extracted (e.g. "A")
- **model** (int) - Optional - Index of model to be extracted (default: 0)

### Response
#### Success Response (200)
- **Chain** (object) - Chain object containing DataFrames listing residues and atom coordinates
```

--------------------------------

### POST /protocol/standard

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/align/protocol.html

Executes the standard buildali4 workflow, which performs an iterative jackhmmer search and prepares the output configuration for downstream analysis.

```APIDOC
## POST /protocol/standard

### Description
Runs the standard iterative jackhmmer search workflow. It handles sequence fetching, region cutting, alignment generation, and result configuration.

### Method
POST

### Parameters
#### Request Body
- **sequence_id** (string) - Required - Identifier for the sequence.
- **sequence_file** (string) - Required - Path to the input sequence file.
- **sequence_download_url** (string) - Optional - URL to download the sequence.
- **region** (string) - Optional - Specific region of the sequence to process.
- **first_index** (int) - Optional - Starting index for the sequence region.
- **use_bitscores** (boolean) - Optional - Whether to use bitscores for thresholds.
- **domain_threshold** (float) - Optional - Threshold for domain inclusion.
- **sequence_threshold** (float) - Optional - Threshold for sequence inclusion.
- **database** (string) - Required - Path or identifier for the sequence database.
- **iterations** (int) - Optional - Number of jackhmmer iterations.
- **cpu** (int) - Optional - Number of CPU cores to use.
- **nobias** (boolean) - Optional - Whether to disable bias filter.
- **reuse_alignment** (boolean) - Optional - Whether to reuse existing alignment results.
- **checkpoints_hmm** (string) - Optional - Path for HMM checkpoints.
- **checkpoints_ali** (string) - Optional - Path for alignment checkpoints.
- **jackhmmer** (string) - Optional - Path to the jackhmmer binary.
- **prefix** (string) - Required - Prefix for output files.

### Response
#### Success Response (200)
- **target_sequence_file** (string) - Path to the target sequence file.
- **sequence_file** (string) - Path to the full sequence file.
- **focus_mode** (boolean) - Indicates if focus mode is active.
- **raw_alignment_file** (string) - Path to the generated alignment file.
- **hittable_file** (string) - Path to the domain table output file.
- **segments** (list) - List of protein segments defined.
- **focus_sequence** (string) - Identifier for the focus sequence region.
```

--------------------------------

### Starting a New Feature Branch

Source: https://github.com/debbiemarkslab/evcouplings/wiki/EVcouplings-Git-Workflow

Creates a new feature branch based on the current develop branch.

```bash
git checkout develop
git checkout -b feature/your-cool-new-feature
```

--------------------------------

### Initialize SIFTS Database

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/distance_calculations.ipynb

Loads index mapping information from SIFTS files, creating them automatically if they do not exist.

```python
s = SIFTS("../../databases/sifts/pdb_chain_uniprot_plus.csv", "../../databases/sifts/pdb_chain_uniprot_plus.fa")
```

--------------------------------

### Retrieve Symbol for Specific Position

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/model_parameters_mutation_effects.ipynb

Get the amino acid symbol at a particular position in the wild-type sequence.

```python
# symbol for particular position (or list of positions)
print(c.seq(127))
```

--------------------------------

### Execute Single Configuration File with evcouplings_runcfg

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/running_jobs.ipynb

This command-line tool executes a single configuration file, running a single thread of the pipeline and ignoring any 'batch' settings.

```bash
evcouplings_runcfg <config_file>
```

--------------------------------

### Target Sequence Management

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/couplings/model.html

APIs for getting and setting the target sequence, which is used for delta Hamiltonian calculations.

```APIDOC
## Target Sequence API

### Description
Manages the target sequence used for delta Hamiltonian calculations, including single and double mutation matrices.

### Method
`target_seq` (getter and setter)

### Endpoint
(Not applicable - this is a property of a loaded model object)

### Parameters
#### Setter Parameters
- **sequence** (str or list of chars) - Required - The new target sequence. Its length must match the model length (`self.L`).

### Request Example (Setter)
```python
model.target_seq = "ACDEFGHIKLMNPQRSTVWY"
```

### Response (Getter)
- **target_seq** (numpy.ndarray) - The current target sequence as a NumPy array of unicode characters.

### Response Example (Getter)
```json
{
  "target_seq": ["A", "C", "D", "E", "F", "G", "H", "I", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y"]
}
```

### Error Handling
- Raises `ValueError` if the provided sequence length does not match the model length (`self.L`).
```

--------------------------------

### Initialize Pipeline Backend and Imports

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/pipeline.html

Configures the matplotlib backend for non-interactive command-line usage and imports necessary system, configuration, and protocol modules.

```python
import matplotlib
matplotlib.use("Agg")

import signal
import os
from os import path
import sys
import traceback
import tarfile

import click

from evcouplings.utils.config import (
    read_config_file, check_required, write_config_file,
    InvalidParameterError
)
from evcouplings.utils.system import (
    create_prefix_folders, insert_dir, verify_resources,
    valid_file
)
from evcouplings.utils.database import (
    update_job_status, EStatus
)

import evcouplings.align.protocol as ap
import evcouplings.couplings.protocol as cp
import evcouplings.compare.protocol as cm
import evcouplings.mutate.protocol as mt
import evcouplings.fold.protocol as fd
import evcouplings.complex.protocol as pp
```

--------------------------------

### evcouplings.fold.protocol.run

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.fold.html

Runs the folding protocol.

```APIDOC
## POST /evcouplings/fold/protocol/run

### Description
Run folding protocol.

### Method
POST

### Endpoint
/evcouplings/fold/protocol/run

### Parameters
#### Request Body
- **kwargs** (dict) - Mandatory - Arguments for the protocol. Must include 'protocol' (Folding protocol to run) and 'prefix' (Output prefix for all generated files).

### Response
#### Success Response (200)
- **outcfg** (dict) - Output configuration of stage (see individual protocol for fields)

#### Response Example
{
  "outcfg": "{...}"
}
```

--------------------------------

### ScalarObjectAttributeImpl Get History

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/sqlalchemy/orm/attributes.html

Retrieves the history of a scalar-holding instrumented attribute, handling passive modes and missing values.

```python
def get_history(self, state, dict_, passive=PASSIVE_OFF):
        if self.key in dict_:
            return History.from_object_attribute(self, state, dict_[self.key])
        else:
            if passive & INIT_OK:
                passive ^= INIT_OK
            current = self.get(state, dict_, passive=passive)
            if current is PASSIVE_NO_RESULT:
                return HISTORY_BLANK
            else:
                return History.from_object_attribute(self, state, current)
```

--------------------------------

### evcouplings.utils.system.run

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.utils.html

Executes an external program as a subprocess.

```APIDOC
## evcouplings.utils.system.run

### Description
Run an external program as a subprocess.

### Parameters
- **cmd** (str or list of str) - Required - Command and optional arguments
- **stdin** (str or byte sequence) - Optional - Input to be sent to STDIN
- **check_returncode** (bool) - Optional - Verify if returncode == 0, raises ExternalToolError if not
- **working_dir** (str) - Optional - Directory to change to before execution
- **shell** (bool) - Optional - Invoke shell when calling subprocess
- **env** (dict) - Optional - Environment variables for the subprocess

### Response
- **return_code** (int) - Return code of the process
- **stdout** (byte string) - Standard output
- **stderr** (byte string) - Standard error
```

--------------------------------

### Initialize PDB Structure from File

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/compare/pdb.html

Initializes a PDB structure from a local file, supporting both PDB and mmCIF formats.

```APIDOC
## POST /api/pdb/from_file

### Description
Initializes a PDB structure from a local file.

### Method
POST

### Endpoint
/api/pdb/from_file

### Parameters
#### Request Body
- **filename** (str) - Required - Path of the PDB or mmCIF file.
- **file_format** (str) - Optional - Format of the structure. Accepts 'pdb' or 'cif'. Defaults to 'pdb'.

### Request Example
```json
{
  "filename": "/path/to/your/structure.pdb",
  "file_format": "pdb"
}
```

### Response
#### Success Response (200)
- **structure** (object) - The initialized PDB structure object.

#### Response Example
```json
{
  "structure": {
    "id": "initialized_structure_id"
  }
}
```
```

--------------------------------

### Get alignment dimensions

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/alignment_analysis.ipynb

Prints the length (number of columns) and the number of sequences (number of rows) in the alignment object.

```python
# Sequence length and number of sequences
print(f"alignment is of length {aln.L} and has {aln.N} sequences")
```

--------------------------------

### Get Chain Information

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/compare/pdb.html

Extracts residue information and atom coordinates for a specified chain within a PDB structure.

```APIDOC
## GET /api/pdb/{structure_id}/chain/{chain_id}

### Description
Extracts residue information and atom coordinates for a given chain in a PDB structure.

### Method
GET

### Endpoint
/api/pdb/{structure_id}/chain/{chain_id}

### Parameters
#### Path Parameters
- **structure_id** (str) - Required - Identifier for the PDB structure.
- **chain_id** (str) - Required - Name of the chain to be extracted (e.g., 'A').

#### Query Parameters
- **model** (int) - Optional - Index of the model to be extracted. Defaults to 0.

### Response
#### Success Response (200)
- **chain_data** (object) - An object containing residue and coordinate DataFrames for the specified chain.
  - **residues** (DataFrame) - DataFrame with residue information (ID, sequence, etc.).
  - **coordinates** (DataFrame) - DataFrame with atom coordinates.

#### Response Example
```json
{
  "chain_data": {
    "residues": {
      "id": ["1", "2", ...],
      "seqres_id": [null, null, ...],
      "coord_id": ["1", "2", ...],
      "one_letter_code": ["A", "R", ...],
      "three_letter_code": ["ALA", "ARG", ...],
      "chain_index": [null, null, ...],
      "chain_id": [null, null, ...],
      "sec_struct": [null, null, ...],
      "sec_struct_3state": [null, null, ...],
      "hetatm": [false, false, ...]
    },
    "coordinates": {
      "residue_index": [0, 0, ..., 1, 1, ...],
      "atom_index": [0, 1, ..., 0, 1, ...],
      "atom_id": ["N", "CA", ..., "N", "CA", ...],
      "x": [1.0, 2.0, ..., 1.5, 2.5, ...],
      "y": [3.0, 4.0, ..., 3.5, 4.5, ...],
      "z": [5.0, 6.0, ..., 5.5, 6.5, ...],
      "b_factor": [20.0, 22.0, ..., 21.0, 23.0, ...],
      "alt_loc": [" ", " ", ..., " ", " ", ...],
      "occupancy": [1.0, 1.0, ..., 1.0, 1.0, ...],
      "charge": [null, null, ..., null, null, ...]
    }
  }
}
```
```

--------------------------------

### Load and inspect alignment file with EVcouplings

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/notebooks/output_files_tutorial.ipynb

Demonstrates how to load an alignment file (e.g., .a2m format) using the EVcouplings Alignment module and print its dimensions. It also shows how to retrieve and print a specific sequence from the alignment.

```python
from evcouplings.align import Alignment

# Load the alignment - format will be detected automatically but can also be set manually
with open("example/PABP_YEAST.a2m") as f:
    aln = Alignment.from_file(f)

print("Alignment has {} sequences and {} columns".format(aln.N, aln.L))

#retrieve a particular sequence
sequence_id = "PABP_YEAST/115-210" #IDENTIFIER/POS_START-POS_END
print(sequence_id, "".join(aln[sequence_id]))
```

--------------------------------

### Get FN Scores

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/couplings/model.html

Property to retrieve the FN (Frobenius norm) scores. Calculates the scores if they haven't been computed yet.

```python
return self._fn_scores
```

--------------------------------

### PDB.from_file

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/evcouplings.compare.html

Initializes a PDB structure from a local MMTF file.

```APIDOC
## PDB.from_file

### Description
Initialize structure from MMTF file.

### Parameters
- **filename** (str) - Required - Path of MMTF file

### Response
- **PDB** (object) - Initialized PDB structure
```

--------------------------------

### Define documentation options

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/abc.html

Global configuration object for Sphinx documentation.

```javascript
var DOCUMENTATION_OPTIONS = { URL_ROOT:'../', VERSION:'0.0.1', COLLAPSE_INDEX:false, FILE_SUFFIX:'.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '.txt' }; jQuery(function () { SphinxRtdTheme.StickyNav.enable(); });
```

--------------------------------

### Get CN Scores

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/couplings/model.html

Property to retrieve the CN (corrected norm) scores. Calculates the scores if they haven't been computed yet.

```python
return self._cn_scores
```

--------------------------------

### Model Loading and Initialization

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/couplings/model.html

This section details the process of loading an EVcouplings model from a file, including handling different alphabet formats and data types.

```APIDOC
## Model Loading from File

### Description
Loads model parameters (length, number of symbols, alphabet, sequences, frequencies, couplings) from a binary file.

### Method
`__init__` (constructor)

### Parameters
- **filename** (str) - Required - Path to the binary model file.
- **alphabet** (str, optional) - The alphabet to use for the model. If None, it attempts to guess based on `num_symbols`.
- **precision** (str, optional) - Data type for floating-point numbers (e.g., 'f4' for float32, 'f8' for float64).

### Request Body
(Not applicable for constructor)

### Response
(Not applicable for constructor)

### Error Handling
- Raises `ValueError` if the alphabet size does not match `num_symbols`.
- Raises `ValueError` if the file contains inconsistent column pair indices.
```

--------------------------------

### Python: Render Jinja2 template

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/evcouplings.utils.md

Renders a Jinja2 template by substituting values from a provided mapping. Requires the Jinja2 library to be installed.

```python
def render_template(template_file, mapping):
    # Render a template using jinja2 and substitute
    # values from mapping
    # Parameters:
    #   template_file (str): Path to jinja2 template
    #   mapping (dict): Mapping used to substitute values
    #     in the template
    # Returns:
    # Rendered template
    # Return type:
    # str
    
    env = jinja2.Environment(loader=jinja2.FileSystemLoader(os.path.dirname(template_file)))
    template = env.get_template(os.path.basename(template_file))
    return template.render(**mapping)

```

--------------------------------

### Run Folding Protocol

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/fold/protocol.html

The `run` function serves as the entry point for executing folding protocols within EVcouplings. It accepts a protocol name and other keyword arguments required by the selected protocol.

```APIDOC
## POST /evcouplings/fold/protocol/run

### Description
Executes a specified folding protocol with the given parameters.

### Method
POST

### Endpoint
/evcouplings/fold/protocol/run

### Parameters
#### Query Parameters
- **protocol** (string) - Required - The name of the folding protocol to run (e.g., "standard").
- **prefix** (string) - Required - Output prefix for all generated files.

### Request Body
This endpoint accepts arbitrary keyword arguments that are passed directly to the selected folding protocol.

### Request Example
```json
{
  "protocol": "standard",
  "prefix": "my_folding_run",
  "distance_cutoff": 10.0,
  "norm_by_intersection": true
}
```

### Response
#### Success Response (200)
- **folding_comparison_file** (string) - Path to the generated CSV file containing the overall folding comparison.
- **folding_individual_comparison_files** (dict) - A dictionary where keys are paths to individual comparison CSV files for each structure, and values are the original experimental file paths.

#### Response Example
```json
{
  "folding_comparison_file": "./my_folding_run_comparison.csv",
  "folding_individual_comparison_files": {
    "./output_dir/structure1.csv": "./data/structure1.pdb",
    "./output_dir/structure2.csv": "./data/structure2.pdb"
  }
}
```
```

--------------------------------

### find_secondary_structure_segments

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/visualize/pairs.html

Identifies segments of secondary structure elements (H, E, -/C) from a given string and returns their start and end positions.

```APIDOC
## find_secondary_structure_segments

### Description
Identifies segments of secondary structure elements in a string and returns the start/end indices and a list of segments.

### Parameters
#### Query Parameters
- **sse_string** (str) - Required - String with secondary structure states of sequence ("H", "E", "-"/"C")
- **offset** (int) - Optional - Shift start/end indices of segments by this offset (default: 0)

### Response
#### Success Response (200)
- **start** (int) - Index of first position
- **end** (int) - Index of last position
- **segments** (list) - List of tuples containing (element, start_pos, end_pos_exclusive)
```

--------------------------------

### GET /external-resource

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/system.html

Downloads an external resource from a specified URL. Supports optional saving to a local file path and redirect handling.

```APIDOC
## GET /external-resource

### Description
Downloads an external resource from a given URL. Returns a response object containing the content.

### Parameters
#### Query Parameters
- **url** (str) - Required - URL of the resource to download
- **output_path** (str) - Optional - Path to save the downloaded content
- **allow_redirects** (bool) - Optional - Whether to allow server redirects

### Response
#### Success Response (200)
- **r** (requests.models.Response) - The response object containing the resource data
```

--------------------------------

### Initialize Job Submission with Database Path

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/batch.html

Initializes the job submission system, optionally using a temporary or specified LevelDB for command persistence. Ensures the database is properly closed and removed if temporary.

```python
def __init__(self, blocking=False, db_path=None):
    """
    Init function

    Parameters
    ----------
    blocking: bool
        determines whether join() blocks or not
    db_path: str
        the string to a LevelDB for command persistence
    """
    self.__blocking = blocking
    if db_path is None:
        tmp_db = NamedTemporaryFile(delete=False, dir=os.getcwd(), suffix=".db")
        tmp_db.close()
        self.__is_temp_db = True
        self.__db_path = tmp_db.name
    else:
        self.__is_temp_db = False
        self.__db_path = db_path

    self.__db = PersistentDict(self.__db_path)
```

```python
def __del__(self):
    try:
        self.__db.close()
        if self.__is_temp_db:
            os.remove(self.__db_path)
    except AttributeError:
        pass
```

--------------------------------

### Attribute Access and Modification

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/sqlalchemy/orm/attributes.html

Functions to interact with object attributes, including getting, setting, and deleting values while triggering necessary history events.

```APIDOC
## GET /attribute

### Description
Retrieves the value of an attribute, firing any callables required.

### Parameters
#### Request Body
- **instance** (object) - Required - The instrumented object instance.
- **key** (string) - Required - The name of the attribute.

## POST /attribute/set

### Description
Sets the value of an attribute, firing history events.

### Parameters
#### Request Body
- **instance** (object) - Required - The instrumented object instance.
- **key** (string) - Required - The name of the attribute.
- **value** (any) - Required - The value to set.

## DELETE /attribute

### Description
Deletes the value of an attribute, firing history events.

### Parameters
#### Request Body
- **instance** (object) - Required - The instrumented object instance.
- **key** (string) - Required - The name of the attribute.
```

--------------------------------

### Initialize PDB structure from file or ID

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/compare/pdb.html

Factory methods to create a PDB instance from a local MMTF file or by fetching from RCSB servers.

```python
@classmethod
def from_file(cls, filename):
    """
    Initialize structure from MMTF file

    Parameters
    ----------
    filename : str
        Path of MMTF file

    Returns
    -------
    PDB
        initialized PDB structure
    """
    try:
        return cls(parse(filename))
    except FileNotFoundError as e:
        raise ResourceError(
            "Could not find file {}".format(filename)
        ) from e
```

```python
@classmethod
def from_id(cls, pdb_id):
    """
    Initialize structure by PDB ID (fetches
    structure from RCSB servers)

    Parameters
    ----------
    pdb_id : str
        PDB identifier (e.g. 1hzx)

    Returns
    -------
    PDB
        initialized PDB structure
    """
    try:
        return cls(fetch(pdb_id))
    except HTTPError as e:
        raise ResourceError(
            "Could not fetch MMTF data for {}".format(pdb_id)
        ) from e
```

--------------------------------

### Prepare Job Dependencies from Database

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/evcouplings/utils/batch.html

Constructs the dependency string for job submission based on dependent commands. It retrieves job IDs from the database and formats them for the submission command.

```python
def _prepare_dependencies(self, dependent):
    dep = ""
    if dependent is not None:
        try:
            if isinstance(dependent, Command):
                d_info = yaml.load(self.__db[dependent.command_id], yaml.RoundTripLoader)
                dep = "-w {}".format(d_info["job_id"])
            else:
                dep_jobs = []
                for d in dependent:
                    d_info = yaml.load(self.__db[d.command_id], yaml.RoundTripLoader)
                    dep_jobs.append(d_info["job_id"])
                # not sure if comma-separated is correct
                dep = "-w {}".format(" && ".join("ended({})".format(d) for d in dep_jobs))
        except KeyError:
            raise ValueError("Specified depended jobs have not been submitted yet.")
    return dep
```

--------------------------------

### Get Collection History

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/sqlalchemy/orm/attributes.html

Retrieves the history of changes for a collection attribute. It returns a History object representing the collection's state changes.

```python
def get_history(self, state, dict_, passive=PASSIVE_OFF):
        current = self.get(state, dict_, passive=passive)
        if current is PASSIVE_NO_RESULT:
            return HISTORY_BLANK
        else:
            return History.from_collection(self, state, current)
```

--------------------------------

### Get Attribute Value

Source: https://github.com/debbiemarkslab/evcouplings/blob/develop/docs/_build/html/_modules/sqlalchemy/orm/attributes.html

Retrieves the value of the attribute from the given state and dictionary. If a callable is associated with the attribute and `passive` is `False`, the callable will be executed.

```python
def get(self, state, dict_, passive=PASSIVE_OFF):
        """Retrieve a value from the given object.
        If a callable is assembled on this object's attribute, and
        passive is False, the callable will be executed and the

```