HyPhy

https://www.hyphy.org/
Admin
HyPhy is an open-source software package for comparative sequence analysis using stochastic...
Tokens:44,443
Snippets:237
Trust Score:9
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install HyPhy

Source: https://www.hyphy.org/installation

Installs the compiled HyPhy executables and libraries onto the system. The installation location is determined by the CMake configuration, defaulting to /usr/local/.

```bash
make install
```

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

### Configure HyPhy Build with CMake

Source: https://www.hyphy.org/installation

Configures the HyPhy build using CMake. By default, it installs to /usr/local/. Custom installation paths, Xcode generator, or specific compilers can be specified.

```bash
cmake .
cmake -DCMAKE_INSTALL_PREFIX=/location/of/choice .
cmake -G Xcode .
cmake . -DCMAKE_CXX_COMPILER=/path/to/C++-compiler -DCMAKE_C_COMPILER=/path/to/C-compiler
```

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

### Navigate to HyPhy Directory

Source: https://www.hyphy.org/installation

Changes the current directory to the root of the downloaded or cloned HyPhy source code repository. This is the first step before configuring the build.

```bash
cd hyphy
```

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

### Install HyPhy using Conda

Source: https://www.hyphy.org/installation

Installs HyPhy, including both MP and MPI versions, using the bioconda channel. Ensure the bioconda channel is added if it's not already present.

```bash
conda install -c bioconda hyphy
conda config --add channels bioconda
```

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

### Build HyPhy Executables (MP and MPI)

Source: https://www.hyphy.org/installation

Builds the HyPhy executables. 'make MP' builds the multi-threaded version using OpenMP, and 'make MPI' builds the parallel version using MPI. The -j flag speeds up the compilation.

```bash
make MP
make -j MP
make MPI
```

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

### Specify macOS SDK for CMake

Source: https://www.hyphy.org/installation

Configures the HyPhy build using CMake on macOS, specifying the SDK version to use for compilation. This ensures compatibility with specific macOS versions.

```bash
cmake -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.9.sdk/ .
```

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

### Get Ancestral Sequences (Hyphy)

Source: https://www.hyphy.org/hbl-reference/libv3

Infers and retrieves ancestral sequences based on ancestral data, typically generated by `ancestral.build`. It returns a dictionary where keys are node names and values are the inferred ancestral sequences.

```hyphy
def get_ancestral_sequences(ancestral_data: dict) -> dict:
    """Gets ancestral sequences

    Args:
        ancestral_data (dict): the dictionary returned by ancestral.build

    Returns:
        dict: { "Node Name" : {String} inferred ancestral sequence, }
    """
    pass
```

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

### Get Bootstrap Support for Tree Nodes

Source: https://www.hyphy.org/hbl-reference/libv3

Calculates and returns bootstrap support values for the nodes of a tree. The function takes a tree information object as input. The output is a dictionary mapping node names to their corresponding bootstrap support values. This dictionary may be empty or partially filled.

```python
bootstrap_support = trees.BootstrapSupport(tree_info_object);
# bootstrap_support is a dictionary like {"node name": bootstrap_value}
```

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

### Set HyPhy Library Path Environment Variable

Source: https://www.hyphy.org/installation

Sets the HYPHY_LIB_PATH environment variable to specify the directory where HyPhy searches for its library sources. This allows HyPhy to find its necessary scripts and data files.

```bash
export HYPHY_LIB_PATH=/usr/local/lib/hyphy/
hyphy
```

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

### Get Model Parameters by RegExp

Source: https://www.hyphy.org/hbl-reference/libv3

Retrieves global model parameters matching a regular expression.

```APIDOC
## model.GetParameters_RegExp

### Description
Retrieves a dictionary of global model parameters that match a given regular expression.

### Method
GET (assumed)

### Endpoint
/websites/hyphy/model.GetParameters_RegExp

### Parameters
#### Path Parameters
None

#### Query Parameters
* **model** (String) - Required - The ID of the model.
* **re** (String) - Required - The regular expression to match parameter names.

### Request Example
```json
{
  "model": "model_123",
  "re": ".*global.*"
}
```

### Response
#### Success Response (200)
* **any** - A dictionary of global model parameters matching the regular expression.
```

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

### Get Branch Lengths in String Format

Source: https://www.hyphy.org/hbl-reference/libv3

Retrieves branch lengths of a tree in a string format.

```APIDOC
## estimators.branch_lengths_in_string

### Description
Get the branch lengths of a tree in a string format.

### Method
POST (Assumed, as it retrieves data)

### Endpoint
/websites/hyphy/estimators/branch_lengths_in_string

### Parameters
#### Request Body
- `tree_id` (String) - Required - The ID of the tree.
- `lookup` (String) - Required - A lookup string or format specifier.

### Response
#### Success Response (200)
- `branch_lengths` (String) - A string representation of the branch lengths.

### Response Example
```json
{
  "branch_lengths": "(A:0.1,B:0.2);"
}
```
```

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

### Estimators - Create Initial Grid

Source: https://www.hyphy.org/hbl-reference/libv3

Prepares a dictionary object suitable for seeding initial LF values.

```APIDOC
## estimators.CreateInitialGrid

### Description
Prepare a Dict object suitable for seeding initial LF values.

### Method
POST (Assumed, as it generates data)

### Endpoint
/websites/hyphy/estimators/CreateInitialGrid

### Parameters
#### Request Body
- `values` (Dict) - Required - A dictionary mapping parameter IDs to initial value sets. Example: `{"parameter_id": {{initial_values_set}}}`
- `N` (int) - Required - The number of points to sample.
- `init` (Dict/null) - Optional - If not null, serves as an initial template for variables.

### Response
#### Success Response (200)
- `initial_grid` (Dict) - A dictionary containing the initial grid points.

### Response Example
```json
{
  "initial_grid": {
    "0": {
      "busted.test.bsrel_mixture_aux_0": {"ID": "busted.test.bsrel_mixture_aux_0", "MLE": 0.4},
      "busted.test.bsrel_mixture_aux_1": {"ID": "busted.test.bsrel_mixture_aux_1", "MLE": 0.7},
      "busted.test.omega1": {"ID": "busted.test.omega1", "MLE": 0.01},
      "busted.test.omega2": {"ID": "busted.test.omega2", "MLE": 0.1},
      "busted.test.omega3": {"ID": "busted.test.omega3", "MLE": 1.5}
    }
  }
}
```
```

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

### Load Annotated Tree Topology with Partition Matching

Source: https://www.hyphy.org/hbl-reference/libv3

Loads a tree topology along with node name label mappings and annotations from a list of partitions. It requires a list of partition names and a dictionary mapping node names to labels. The function returns a dictionary of matched partitions.

```python
hky85_nucdata_info = alignments.ReadNucleotideAlignment(file_name, "hky85.nuc_data", "hky85.nuc_filter");
 name_mapping = {
  "HUMAN":"HUMAN",
  "CHIMP":"CHIMP",
  "BABOON":"BABOON",
  "RHMONKEY":"RHMONKEY",
  "COW":"COW",
  "PIG":"PIG",
  "HORSE":"HORSE",
  "CAT":"CAT",
  "MOUSE":"MOUSE",
  "RAT":"RAT"
 };
trees.LoadAnnotatedTreeTopology.match_partitions(hky85_nucdata_info[terms.json.partitions], name_mapping);
=>
{
 "0":{
  "name":"default",
  "filter-string":"",
  "tree": *
 }
}
```

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

### LoadAnnotatedTreeTopology.match_partitions

Source: https://www.hyphy.org/hbl-reference/libv3

Loads a tree topology with node name label mappings and annotations from a list of partitions.

```APIDOC
## LoadAnnotatedTreeTopology.match_partitions

### Description
Loads a tree topology with node name label mappings and annotations from a list of partitions.

### Method
POST (assumed, as it modifies/loads data)

### Endpoint
/websites/hyphy/trees/LoadAnnotatedTreeTopology/match_partitions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **partitions** (Matrix) - Required - A 1xN vector of partition names.
- **mapping** (Dictionary) - Required - A mapping of node names to labels.

### Request Example
```json
{
  "partitions": "[partitions_data]",
  "mapping": {
    "HUMAN": "HUMAN",
    "CHIMP": "CHIMP",
    "BABOON": "BABOON",
    "RHMONKEY": "RHMONKEY",
    "COW": "COW",
    "PIG": "PIG",
    "HORSE": "HORSE",
    "CAT": "CAT",
    "MOUSE": "MOUSE",
    "RAT": "RAT"
  }
}
```

### Response
#### Success Response (200)
- **Dictionary** - A dictionary of matched partitions.

#### Response Example
```json
{
  "0": {
    "name": "default",
    "filter-string": "",
    "tree": "*"
  }
}
```
```

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

### trees.GetBranchCount

Source: https://www.hyphy.org/hbl-reference/libv3

Gets the total number of branches in a tree.

```APIDOC
## trees.GetBranchCount

### Description
Calculates and returns the total count of branches in the provided tree string.

### Method
POST (assumed, as it processes input string)

### Endpoint
/websites/hyphy/trees/GetBranchCount

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tree_string** (String) - Required - The Newick formatted tree string.

### Request Example
```json
{
  "tree_string": "(A:1,B:2);"
}
```

### Response
#### Success Response (200)
- **Number** - The total number of branches in the tree.

#### Response Example
```json
2
```
```

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

### Get Global MLE

Source: https://www.hyphy.org/hbl-reference/libv3

Retrieves the global Maximum Likelihood Estimate (MLE) from a results dictionary.

```APIDOC
## estimators.GetGlobalMLE

### Description
Retrieve the global Maximum Likelihood Estimate (MLE) from a results dictionary based on a tag.

### Method
POST (Assumed, as it retrieves data)

### Endpoint
/websites/hyphy/estimators/GetGlobalMLE

### Parameters
#### Request Body
- `results` (Dictionary) - Required - The dictionary containing estimation results.
- `tag` (String) - Required - The tag to identify the global MLE.

### Response
#### Success Response (200)
- `global_mle` (any) - The value of the global MLE.

### Response Example
```json
{
  "global_mle": 0.85
}
```
```

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

### BuildAncestralStates

Source: https://www.hyphy.org/hbl-reference/libv3

Builds ancestral states for phylogenetic analysis.

```APIDOC
## ancestral.build

### Description
Builds ancestral states for phylogenetic analysis. This function prepares the data structure required for subsequent ancestral state computations.

### Method
POST

### Endpoint
/websites/hyphy/ancestral/build

### Parameters
#### Query Parameters
- **_lfID** (Number) - Required - The likelihood function ID.
- **_lfComponentID** (Number) - Required - The likelihood function component ID.
- **options** (options) - Required - Options object for building ancestral states.

### Response
#### Success Response (200)
- **ancestral_data_id** (any) - An integer index to reference the opaque structure for subsequent operations.

#### Response Example
```json
{
  "ancestral_data_id": 12345
}
```
```

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

### model.define_from_components

Source: https://www.hyphy.org/hbl-reference/libv3

Defines a model from its components: Q matrix and equilibrium frequencies.

```APIDOC
## model.define_from_components#

### Description
Defines a model from its components: Q matrix and equilibrium frequencies.

### Parameters
#### Path Parameters
- `id` (String) - Name of the Model
- `q` (Matrix) - instantaneous transition matrix
- `evf` (Matrix) - the equilibrium frequencies
- `canonical` (Number) - matrix exponential

### Examples
```
q = {{*,t,kappa*t,t}
 {t,*,t,t*kappa}
 {t*kappa,t,*,t}
 {t,t*kappa,t,*}};
evf =  {{0.4}{0.3}{0.2}{0.1}};
model.define_from_components(q,evf,1);
```

### Returns
**any** nothing, sets a global {Model}
```

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

### alignments.ReadCodonDataSet

Source: https://www.hyphy.org/hbl-reference/libv3

Retrieves metadata from an existing codon dataset by its ID. This function is used to get information about previously loaded codon datasets.

```APIDOC
## alignments.ReadCodonDataSet

### Description
Get metadata from existing codon dataset.

### Method
GET

### Endpoint
/websites/hyphy/alignments/read_codon_metadata

### Parameters
#### Query Parameters
- **dataset_name** (String) - Required - The ID of the codon dataset to retrieve metadata for.

### Response
#### Success Response (200)
- **metadata** (Dictionary) - Metadata pertaining to the specified codon dataset.

#### Response Example
```json
{
  "metadata": {
    "num_sequences": 12,
    "num_sites": 180,
    "genetic_code": "Mitochondrial (Invertebrate)"
  }
}
```
```

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

### trees.ParsimonyLabel (1st Version)

Source: https://www.hyphy.org/hbl-reference/libv3

Computes branch labeling using parsimony.

```APIDOC
## trees.ParsimonyLabel (Parsimony Labeling)

### Description
Computes branch labeling for a tree based on parsimony principles, considering provided leaf labels which may be incomplete.

### Method
POST (assumed, as it performs computation)

### Endpoint
/websites/hyphy/trees/ParsimonyLabel

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tree** (String) - Required - The ID or representation of the tree.
- **leaf** (Dict) - Required - A dictionary mapping leaf identifiers to their labels. Labels might be missing for some leaves.

### Request Example
```json
{
  "tree": "tree_id",
  "leaf": {
    "leaf1": "labelA",
    "leaf2": "labelB"
  }
}
```

### Response
#### Success Response (200)
- **Dict** - A dictionary containing:
  - "score" (Number): The parsimony score.
  - "labels" (Object): An object mapping internal branches to their computed labels.

#### Response Example
```json
{
  "score": 10,
  "labels": {
    "internal_branch_1": "labelX",
    "internal_branch_2": "labelY"
  }
}
```
```

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

### Get Amino Acid Resolutions (Python)

Source: https://www.hyphy.org/hbl-reference/libv3

Retrieves a dictionary of possible amino acids at each position in a sequence, considering a genetic code and a lookup dictionary. This function is useful for analyzing sequence ambiguities.

```python
def get_amino_acid_resolutions(sequence: str, offset: int, code: dict, lookup: dict) -> dict:
    """Returns a dict of possible amino acids at this position

    Args:
        sequence (str): the string to translate
        offset (int): start at this position (should be in {0,1,2})
        code (dict): genetic code description (e.g. returned by alignments.LoadGeneticCode)
        lookup (dict): resolution lookup dictionary

    Returns:
        dict: list of possible amino-acids (as dicts) at this position
    """
    pass
```

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

### trees.BootstrapSupport

Source: https://www.hyphy.org/hbl-reference/libv3

Calculates bootstrap support values for tree nodes.

```APIDOC
## trees.BootstrapSupport

### Description
Computes bootstrap support values for the nodes of a given tree.

### Method
POST (assumed, as it performs analysis)

### Endpoint
/websites/hyphy/trees/BootstrapSupport

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tree** (Dictionary) - Required - The tree information object, typically returned by LoadAnnotatedTopology.

### Request Example
```json
{
  "tree": { ... tree object ... }
}
```

### Response
#### Success Response (200)
- **Dictionary** - A dictionary where keys are node names and values are their corresponding bootstrap support values. This dictionary might be empty or partially filled.

#### Response Example
```json
{
  "node1": 95,
  "node2": 80
}
```
```

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

### Get Total Branch Count of a Tree

Source: https://www.hyphy.org/hbl-reference/libv3

Calculates the total number of branches in a given tree. The function accepts the tree as a string representation and returns the total count as a number. This is useful for basic tree analysis and comparison.

```python
branch_count = trees.GetBranchCount(tree_string);
# branch_count is the total number of branches.
```

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

### estimators.FitSingleModel_Ext

Source: https://www.hyphy.org/hbl-reference/libv3

Fits a single model with extended options, including data filter, tree, model definition, initial values, and run options.

```APIDOC
## estimators.FitSingleModel_Ext

### Description
Fits a single model with extended options.

### Method
POST (Assumed)

### Endpoint
/websites/hyphy/estimators/FitSingleModel_Ext

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **data_filter** (DataFilter) - The data filter to use.
- **tree** (Tree) - The tree to use.
- **model** (Dict) - The model definition.
- **initial_values** (Matrix) - The initial parameter values.
- **run_options** (Dict) - Options for running the model fitting.

### Request Example
```json
{
  "data_filter": "DataFilterObject",
  "tree": "TreeObject",
  "model": {},
  "initial_values": [],
  "run_options": {}
}
```

### Response
#### Success Response (200)
- **results** (any) - The results of the model fitting.

#### Response Example
```json
{
  "results": "any results"
}
```
```

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

### Build Ancestral States (Hyphy)

Source: https://www.hyphy.org/hbl-reference/libv3

Builds ancestral states for phylogenetic analysis. This function initializes an internal structure that can be referenced by subsequent ancestral state functions. It requires a likelihood function ID and component ID.

```hyphy
def build_ancestral_states(_lfID: int, _lfComponentID: int, options: any) -> int:
    """Builds ancestral states

    Args:
        _lfID (int): the likelihood function ID
        _lfComponentID (int): -
        options (options): -

    Returns:
        int: an integer index to reference the opaque structure for subsequent operations
    """
    pass
```

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

### Parameter Declaration and Constraint API

Source: https://www.hyphy.org/hbl-reference/libv3

APIs for declaring global parameters and setting various types of parameter constraints.

```APIDOC
## parameters.DeclareGlobal

### Description
Declares a parameter as global.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.DeclareGlobal

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **id** (String) - Required - The ID of the parameter to declare as global.
* **cache** (Matrix) - Optional - A cache associated with the global parameter.

### Request Example
```json
{
  "id": "global_param_1",
  "cache": [[1, 2]]
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.SetConstraint

### Description
Sets a constraint on a parameter.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.SetConstraint

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **or** (String) - Required - Defines the parameter(s) to set the constraint on using an AssociativeList format {id: id(s)}.
* **value** (Number) - Required - The constraint value to set.
* **global_tag** (String) - Optional - The global namespace tag for the parameter.

### Request Example
```json
{
  "or": "{id: \"param_123\"}",
  "value": 0.5,
  "global_tag": "namespace_A"
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.SetProprtionalConstraint

### Description
Constrains a parameter x to be x := C * (current value of x), where C is a scaler variable or expression.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.SetProprtionalConstraint

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **id** (String) - Required - The ID of the parameter(s) to set the constraint on.
* **scaler** (String) - Required - The ID of the 'C' scaler variable or an expression.

### Request Example
```json
{
  "id": "param_456",
  "scaler": "scaler_value_or_expression"
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.
```

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

### Estimators - Latin Hypercube Sampling

Source: https://www.hyphy.org/hbl-reference/libv3

Prepares initial LF values using Latin Hypercube Sampling.

```APIDOC
## estimators.LHC

### Description
Prepare a Dict object suitable for seeding initial LF values based on Latin Hypercube Sampling.

### Method
POST (Assumed, as it generates data)

### Endpoint
/websites/hyphy/estimators/LHC

### Parameters
#### Request Body
- `ranges` (Dict) - Required - A dictionary mapping parameter IDs to their respective ranges (e.g., `{"parameter_id": {"lower_bound": 0, "upper_bound": 1}}`).
- `samples` (Number) - Required - The number of samples to draw.

### Response
#### Success Response (200)
- `initial_values` (Dict) - A dictionary containing the initial values generated by LHC.

### Response Example
```json
{
  "initial_values": {
    "param1": [0.1, 0.5, 0.9],
    "param2": [0.2, 0.6, 0.8]
  }
}
```
```

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

### Compute Nucleotide Equilibrium Frequencies

Source: https://www.hyphy.org/hbl-reference/libv3

Computes equilibrium frequencies at run-time using Q inversion. This function requires the model, namespace, and a DataSetFilter. It returns an updated model dictionary.

```HyPhy
# Example usage (assuming model and namespace are defined):
# model = {}; namespace = "myModel"; datafilter = DataSetFilter();
# updated_model = frequencies.empirical.nucleotide(model, namespace, datafilter);
```

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

### alignments.GetAllSequences

Source: https://www.hyphy.org/hbl-reference/libv3

Retrieves all sequences from a specified dataset and returns them as a dictionary where keys are sequence IDs and values are the sequences themselves.

```APIDOC
## alignments.GetAllSequences

### Description
Get all sequences as "id" : "sequence" dictionary from a given dataset.

### Method
GET

### Endpoint
/websites/hyphy/alignments/sequences

### Parameters
#### Query Parameters
- **dataset_name** (String) - Required - The name of the dataset to retrieve sequences from.

### Response
#### Success Response (200)
- **sequences** (Dict) - A dictionary mapping sequence IDs to their corresponding sequence strings.

#### Response Example
```json
{
  "sequences": {
    "seq1": "ATGCGTACG",
    "seq2": "CGTAGCTAG"
  }
}
```
```

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

### alignments.PromptForGeneticCodeAndAlignment

Source: https://www.hyphy.org/hbl-reference/libv3

Prompts the user for genetic code and alignment information. This is typically used in interactive scenarios.

```APIDOC
## alignments.PromptForGeneticCodeAndAlignment

### Description
Prompts user for genetic code and alignment.

### Method
POST

### Endpoint
/websites/hyphy/alignments/prompt_genetic_code

### Parameters
#### Request Body
- **dataset_name** (String) - Required - The name of the dataset.
- **datafilter_name** (String) - Required - The name of the dataset filter to use.

### Response
#### Success Response (200)
- **metadata** (Dictionary) - Metadata pertaining to the dataset and filter, potentially updated with user input.

#### Response Example
```json
{
  "metadata": {
    "genetic_code_used": "Standard Code",
    "alignment_type": "Codon"
  }
}
```
```

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

### trees.GenerateRandomTree

Source: https://www.hyphy.org/hbl-reference/libv3

Generates a random tree with a specified number of leaves and configuration options for rooting, branch naming, and branch lengths.

```APIDOC
## trees.GenerateRandomTree

### Description
Generates a RANDOM tree on N leaves.

### Method
POST

### Endpoint
/websites/hyphy/trees/generateRandomTree

### Parameters
#### Query Parameters
- **N** (Number) - Required - number of leaves
- **rooted** (Bool) - Required - whether the tree is rooted
- **branch_name** (String) - Optional - if a string, then it is assumed to be a function with an integer argument (node index) that generates branch names; default is to use numeric names
- **branch_length** (String) - Optional - if a string, then it is assumed to be a function with no arguments that generates branch lengths

### Request Example
```json
{
  "N": 10,
  "rooted": true,
  "branch_name": "lambda i: f'Branch_{i}'",
  "branch_length": "lambda: random.random()"
}
```

### Response
#### Success Response (200)
- **Newick Tree String** (String) - The generated Newick tree string

#### Response Example
```json
{
  "newick_tree": "(A:0.1,B:0.2,(C:0.3,D:0.4)E:0.5)F;"
}
```
```

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

### Parameter Calculation and Utility API

Source: https://www.hyphy.org/hbl-reference/libv3

APIs for calculating parameter means, quoting strings, and manipulating matrix expressions.

```APIDOC
## parameters.Mean

### Description
Calculates the mean of a set of values, optionally applying weights.

### Method
GET (assumed)

### Endpoint
/websites/hyphy/parameters.Mean

### Parameters
#### Path Parameters
None

#### Query Parameters
* **values** (Matrix) - Required - The values to calculate the mean of.
* **weights** (Matrix) - Optional - Weights to multiply the values by before calculating the mean.
* **d** (Number) - Optional - This parameter is not used.

### Request Example
```json
{
  "values": [10, 20, 30],
  "weights": [0.5, 0.2, 0.3]
}
```

### Response
#### Success Response (200)
* **Number** - The calculated mean.

## parameters.Quote

### Description
Quotes the given string argument.

### Method
GET (assumed)

### Endpoint
/websites/hyphy/parameters.Quote

### Parameters
#### Path Parameters
None

#### Query Parameters
* **arg** (String) - Required - The string to be quoted.

### Request Example
```json
{
  "arg": "example string"
}
```

### Response
#### Success Response (200)
* **String** - The quoted string.

## parameters.AppendMultiplicativeTerm

### Description
Appends a multiplicative term to an existing matrix expression.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.AppendMultiplicativeTerm

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **expression** (String) - Required - The matrix expression to modify.
* **term** (String) - Required - The multiplier term to append.

### Request Example
```json
{
  "expression": "(A + B)",
  "term": "* C"
}
```

### Response
#### Success Response (200)
* **String** - The modified expression in the format (expression) * (term).

## parameters.AddMultiplicativeTerm

### Description
Scales a matrix by a scalar term, optionally filling empty elements.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.AddMultiplicativeTerm

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **matrix** (Matrix) - Required - The matrix to scale.
* **term** (Number) - Required - The scalar term to multiply the matrix by.
* **do_empties** (Number) - Optional - If 1, fills empty matrix elements with the term.

### Request Example
```json
{
  "matrix": [[1, 2], [3, null]],
  "term": 5,
  "do_empties": 1
}
```

### Response
#### Success Response (200)
* **Matrix** - The new scaled matrix.
```

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

### Extract Site Patterns (Hyphy)

Source: https://www.hyphy.org/hbl-reference/libv3

Extracts site patterns from sequence data based on a provided DataFilter. It returns a dictionary mapping pattern IDs to site information, including whether the site is constant. The output format details the sites associated with each pattern.

```hyphy
def Extract_site_patterns(data_filter: DataFilter) -> any:
    """Extracts site patterns from data filter

    Args:
        data_filter (DataFilter): 

    Returns:
        any: for a data filter, returns a dictionary like this "pattern id": "sites" : sites (0-based) mapping to this pattern "is_constant" : T/F (is the site constant w/matching ambigs)
    """
    pass
```

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

### Parameter Declaration and Manipulation API

Source: https://www.hyphy.org/hbl-reference/libv3

APIs for declaring parameter categories, normalizing ratios, and setting parameter values.

```APIDOC
## parameters.DeclareCategory

### Description
Declares a category for parameters.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.DeclareCategory

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **def** (Dict) - Required - The definition components of the category.

### Request Example
```json
{
  "def": {"name": "category_A", "values": [1, 2, 3]}
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.NormalizeRatio

### Description
Normalizes a ratio N/D.

### Method
GET (assumed)

### Endpoint
/websites/hyphy/parameters.NormalizeRatio

### Parameters
#### Path Parameters
None

#### Query Parameters
* **n** (Number) - Required - The numerator.
* **d** (Number) - Required - The denominator.

### Request Example
```json
{
  "n": 10,
  "d": 5
}
```

### Response
#### Success Response (200)
* **any** - The normalized ratio (N/D).

## parameters.SetValue

### Description
Sets the value of a specified parameter ID.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.SetValue

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **id** (String) - Required - The ID of the parameter to set the value for.
* **value** (Number) - Required - The value to set.

### Request Example
```json
{
  "id": "param_123",
  "value": 42.5
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.SetLocalValue

### Description
Sets the value of a specified parameter within a tree and branch.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.SetLocalValue

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **tree** (String) - Required - The ID of the tree.
* **branch** (String) - Required - The ID of the branch.
* **id** (String) - Required - The ID of the parameter to set the value for.
* **value** (Number) - Required - The value to set.

### Request Example
```json
{
  "tree": "tree_abc",
  "branch": "branch_xyz",
  "id": "param_456",
  "value": 100.0
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.SetValues

### Description
Sets values for specified parameter IDs.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.SetValues

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **desc** (dict) - Required - A dictionary where keys are parameter IDs and values are their corresponding values. Format: {id : id, mle : value}.

### Request Example
```json
{
  "desc": {"param_789": 50.5, "param_012": 75.2}
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.
```

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

### Set Binary Data Equilibrium Frequency Estimator

Source: https://www.hyphy.org/hbl-reference/libv3

Sets the model's equilibrium frequency estimator to Maximum Likelihood (ML) for binary data. It requires the model, namespace, and a DataSetFilter as parameters and returns an updated model dictionary.

```HyPhy
# Example usage (assuming model and namespace are defined):
# model = {}; namespace = "myModel"; datafilter = DataSetFilter();
# updated_model = frequencies.empirical.binary(model, namespace, datafilter);
```

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

### Define Model Components in Hyphy

Source: https://www.hyphy.org/hbl-reference/libv3

Defines a model using its instantaneous transition matrix (q) and equilibrium frequencies (evf). The canonical parameter controls matrix exponentiation. This function is used to set a global Model object.

```HyPhy
q = {{*,t,kappa*t,t}
 {t,*,t,t*kappa}
 {t*kappa,t,*,t}
 {t,t*kappa,t,*}};
evf =  {{0.4}{0.3}{0.2}{0.1}};
model.define_from_components(q,evf,1);
```

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

### Compute Substitution Counts (Hyphy)

Source: https://www.hyphy.org/hbl-reference/libv3

Computes substitution counts between ancestral and descendant sequences. It allows for flexible filtering of branches, substitutions, and sites. The function returns a structured dictionary containing branch names, site indices, and the substitution count matrix.

```hyphy
def compute_substitution_counts(ancestral_data: dict, branch_filter: any = None, substitution_filter: any = None, site_filter: any = None) -> dict:
    """Computes substitution counts

    Args:
        ancestral_data (dict): the dictionary returned by ancestral.build
        branch_filter (dict/Function/None): now to determine the subset of branches to count on None -- all branches Dictionary -- all branches that appear as keys in this dict Function -- all branches on which the function (called with branch name) returns 1
        substitution_filter (Function/None): how to decide if the substitution should count None -- different characters (except anything vs a gap) yields a 1 Function -- callback (state1, state2, ancestral_data) will return the value
        site_filter (Function/None): how to decide which sites will be kept None -- at least one substitution Function -- callback (substitution vector) will T/F

    Returns:
        dict: { "Branches" : {Matrix Nx1} names of selected branches, "Sites" : {Matrix Sx1} indices of sites passing filter, "Counts" : {Matrix NxS} of substitution counts, }N = number of selected branches S = number of sites passing filter
    """
    pass
```

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

### Parameter Constraint Management API

Source: https://www.hyphy.org/hbl-reference/libv3

APIs for constraining parameter sets and unconstraining parameters.

```APIDOC
## parameters.ConstrainMeanOfSet

### Description
Ensures that the mean of parameters in a set is maintained.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.ConstrainMeanOfSet

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **set** (Dict/Matrix) - Required - A list of variable IDs.
* **weights** (Dict/Matrix) - Required - Weights to apply to the parameters.
* **mean** (Number) - Required - The desired mean.
* **namespace** (String) - Required - The desired namespace.

### Request Example
```json
{
  "set": ["var1", "var2"],
  "weights": [0.5, 0.5],
  "mean": 10.0,
  "namespace": "ns1"
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.UnconstrainParameterSet

### Description
Unconstrains a set of parameters within a likelihood function.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.UnconstrainParameterSet

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **lf** (LikelihoodFunction) - Required - The likelihood function to operate on.
* **set** (Matrix) - Required - The set of parameters to unconstrain.

### Request Example
```json
{
  "lf": "likelihood_func_obj",
  "set": ["paramA", "paramB"]
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.

## parameters.ConstrainSets

### Description
Applies constraints between two sets of parameters.

### Method
POST (assumed)

### Endpoint
/websites/hyphy/parameters.ConstrainSets

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **set1** (AssociativeList) - Required - The first set of parameters.
* **set2** (AssociativeList) - Required - The second set of parameters.

### Request Example
```json
{
  "set1": {"param1": "val1", "param2": "val2"},
  "set2": {"param3": "val3", "param4": "val4"}
}
```

### Response
#### Success Response (200)
* **any** - Returns nothing upon successful execution.
```

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

### Extract Branch Information - Copy Local

Source: https://www.hyphy.org/hbl-reference/libv3

Copies local branch information.

```APIDOC
## estimators.ExtractBranchInformation.copy_local

### Description
Copy local branch information.

### Method
POST (Assumed, as it performs an action)

### Endpoint
/websites/hyphy/estimators/ExtractBranchInformation/copy_local

### Parameters
#### Request Body
- `key` (String) - Required - The key for the branch information.
- `value` (String) - Required - The value associated with the key.

### Response
#### Success Response (200)
- `status` (String) - Indicates success or failure.

### Response Example
```json
{
  "status": "success"
}
```
```

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

### trees.GenerateSymmetricTree (Ladder)

Source: https://www.hyphy.org/hbl-reference/libv3

Generates a ladder tree.

```APIDOC
## trees.GenerateSymmetricTree (Ladder Tree)

### Description
Generates a ladder tree structure with a specified number of leaves.

### Method
GET (assumed, as it generates data based on parameters)

### Endpoint
/websites/hyphy/trees/GenerateSymmetricTree/ladder

### Parameters
#### Path Parameters
None

#### Query Parameters
- **N** (Number) - Required - The number of leaves for the tree.
- **rooted** (Bool) - Required - Specifies whether the generated tree should be rooted.
- **branch_name** (None/String) - Optional - A function name (as a string) or None. If a string, it's treated as a function that takes an integer argument (node index) to generate branch names. Defaults to numeric names.
- **branch_length** (None/String) - Optional - A function name (as a string) or None. If a string, it's treated as a function that takes no arguments and generates branch lengths.

### Request Example
```
GET /websites/hyphy/trees/GenerateSymmetricTree/ladder?N=5&rooted=false&branch_name=generateNameFunc
```

### Response
#### Success Response (200)
- **String** - The generated tree in Newick format.

#### Response Example
```json
"((((A:1,B:1):1,C:1):1,D:1):1,E:1);"
```
```

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

### HBL Script: Read and Analyze Nucleotide Data with F81 Model

Source: https://www.hyphy.org/about

This script reads nucleotide sequence data, filters it, defines the F81 substitution model with specified parameters, and then fits this model to the data using maximum likelihood. It outputs the optimized tree with calculated branch lengths.

```hbl
/* 
   This is an example HYPHY Batch File.
   It reads in a MEGA format nucleotide dataset from data/hiv.nuc.
   and fits the F81 model using the tree inclded in the file using maximum likelihood.
   Output is printed out as a Newick Style tree with branch lengths
   representing the number of expected substitutions per branch.
*/

// 1. Read in the data and store the result in a DataSet variable

DataSet         nucleotideSequences = ReadDataFile ("data/hiv.nuc");

// 2. Filter the data, specifying that all of the data is to be used
//  and that it is to be treated as nucleotides.*

DataSetFilter   filteredData = CreateFilter (nucleotideSequences,1);

// Collect observed nucleotide frequencies from the filtered data. observedFreqs will
// store receieve the vector of frequencies. 

HarvestFrequencies (observedFreqs, filteredData, 1, 1, 1);

// Define the F81 substitution matrix. '*' is defined to be -(sum of off-diag row 
// elements); mu is the rate*time parameter 

F81RateMatrix = 
        {{*,mu,mu,mu}
         {mu,*,mu,mu}
         {mu,mu,*,mu}
         {mu,mu,mu,*}};

//  Define the F81 models, by combining the substitution matrix with the vector of observed (equilibrium) frequencies.

Model   F81 = (F81RateMatrix, observedFreqs);

// Now we can define the tree variable, using the tree string read from the data file, 
// and, by default, assigning the last defined model (F81) to all tree branches.

Tree    givenTree = DATAFILE_TREE;

// Since all the likelihood function ingredients (data, tree, equilibrium frequencies)
// have been defined we are ready to construct the likelihood function.

LikelihoodFunction  LF = (filteredData, givenTree);

// Maximize the likelihood function, storing parameter values in the matrix paramValues 

Optimize (paramValues, LF);

// Print the tree with optimal branch lengths to the console. 

fprintf  (stdout, LF);

```

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

### models.DNA.generic.DefineQMatrix

Source: https://www.hyphy.org/hbl-reference/libv3

Defines a Q matrix for DNA models.

```APIDOC
## models.DNA.generic.DefineQMatrix#

### Description
Defines a Q matrix for DNA models.

### Parameters
#### Path Parameters
- `modelSpec` (Dictionary) - Description
- `namespace` (String) - Description
```

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

### estimators.TakeLFStateSnapshot

Source: https://www.hyphy.org/hbl-reference/libv3

Takes a snapshot of the LikelihoodFunction state using its ID.

```APIDOC
## estimators.TakeLFStateSnapshot

### Description
Takes a snapshot of the LikelihoodFunction state.

### Method
POST (Assumed)

### Endpoint
/websites/hyphy/estimators/TakeLFStateSnapshot

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **lf_id** (String) - The ID of the LikelihoodFunction.

### Request Example
```json
{
  "lf_id": "lf_123"
}
```

### Response
#### Success Response (200)
- **snapshot** (Dict) - A dictionary containing parameter estimates and constraints.

#### Response Example
```json
{
  "snapshot": {
    "MLE": 1.23,
    "constraint": "some_constraint"
  }
}
```
```

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

### Set Protein Data Equilibrium Frequency Estimator

Source: https://www.hyphy.org/hbl-reference/libv3

Sets the model's equilibrium frequency estimator to a protein 20x1 estimator. It takes the model, namespace, and a DataSetFilter as input and returns an updated model dictionary.

```HyPhy
# Example usage (assuming model and namespace are defined):
# model = {}; namespace = "myModel"; datafilter = DataSetFilter();
# updated_model = frequencies.empirical.protein(model, namespace, datafilter);
```

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

### trees.LoadAnnotatedTopologyAndMap

Source: https://www.hyphy.org/hbl-reference/libv3

Loads an annotated tree topology and its associated mapping, identified by a dataset name.

```APIDOC
## trees.LoadAnnotatedTopologyAndMap

### Description
Loads an annotated tree topology and its mapping.

### Method
POST (Assumed)

### Endpoint
/websites/hyphy/trees/LoadAnnotatedTopologyAndMap

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **dataset_name** (String) - The name of the dataset to load.

### Request Example
```json
{
  "dataset_name": "my_dataset"
}
```

### Response
#### Success Response (200)
- **annotated_tree_and_map** (Dictionary) - A dictionary containing the annotated tree and its mapping.

#### Response Example
```json
{
  "annotated_tree_and_map": { /* Annotated tree and map data */ }
}
```
```

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

### Fit Likelihood Function

Source: https://www.hyphy.org/hbl-reference/libv3

Creates a likelihood function object with the desired parameters and fits it.

```APIDOC
## estimators.FitLF

### Description
Create a likelihood function object with the desired parameters and fit it to the provided data and trees.

### Method
POST (Assumed, as it creates and fits a function)

### Endpoint
/websites/hyphy/estimators/FitLF

### Parameters
#### Request Body
- `data_filters_list` (Matrix) - Required - A vector of DataFilter objects.
- `tree_list` (Matrix) - Required - A vector of Tree objects.
- `model_map` (any) - Required - The map defining the model.
- `initial_values` (any) - Required - Initial values for the model parameters.

### Response
#### Success Response (200)
- `lf_results` (any) - The results of fitting the LikelihoodFunction.

### Response Example
```json
{
  "lf_results": {
    "log_likelihood": -1600.0,
    "parameters": {"param1": 0.75}
  }
}
```
```
Tokens:
Raw