> ## Documentation Index
> Fetch the complete documentation index at: https://demo.agenticlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# _lbi_jungle.py

## High-level description

The `LBIJungle` class in `cassiopeia/tools/fitness_estimator/_lbi_jungle.py` implements the Lineage Branching Index (LBI) fitness estimator as described by Neher et al. (2014) using the `jungle` package, which is a wrapper around Neher et al.'s original code. This estimator calculates the fitness of each node in a tree based on its branching pattern, with more branching indicating higher fitness.

## Code Structure

The `LBIJungle` class is a subclass of `FitnessEstimator` and overrides the `estimate_fitness` method. It uses the `_to_newick` function to convert the tree to a newick string, which is then used by the `jungle` package to estimate fitness.

## References

* `cassiopeia.data.CassiopeiaTree`
* `cassiopeia.tools.fitness_estimator._FitnessEstimator`
* `jungle` package

## Symbols

### `LBIJungle`

#### Description

This class implements the LBI fitness estimator using the `jungle` package.

#### Inputs

| Name         | Type           | Description                                                  |
| :----------- | :------------- | :----------------------------------------------------------- |
| random\_seed | Optional\[int] | Random seed to use for fitness estimation. Defaults to None. |

#### Outputs

This class does not directly return any outputs. It modifies the input `CassiopeiaTree` object in place.

#### Internal Logic

1. **Check for invalid leaf names:** Raises a `FitnessEstimatorError` if any leaf name starts with an underscore, as this is not supported by the `jungle` package.
2. **Convert tree to newick format:** Uses the `_to_newick` function to convert the tree to a newick string.
3. **Estimate fitness using `jungle` package:**
   * Creates a temporary file to store the newick string.
   * Reads the newick string into a `jungle.Tree` object.
   * Annotates the tree with standard node features.
   * Infers fitness using the `infer_fitness` method of the `jungle.Tree` object.
4. **Set fitness attribute for each node:**
   * Iterates through the nodes and their corresponding fitness values.
   * Sets the `fitness` attribute of each node in the `CassiopeiaTree` object.

## Side Effects

* Modifies the input `CassiopeiaTree` object in place by setting the `fitness` attribute for each node.

## Dependencies

| Dependency | Purpose                                                   |
| :--------- | :-------------------------------------------------------- |
| jungle     | Used to estimate fitness using the LBI method.            |
| networkx   | Used to represent and manipulate the tree topology.       |
| numpy      | Used for random number generation and array manipulation. |

### \_to\_newick

#### Description

This function converts a networkx graph to a newick string.

#### Inputs

| Name                    | Type       | Description                                                                           |
| :---------------------- | :--------- | :------------------------------------------------------------------------------------ |
| tree                    | nx.DiGraph | A networkx tree                                                                       |
| record\_branch\_lengths | bool       | Whether to record branch lengths on the tree in the newick string. Defaults to False. |

#### Outputs

| Name           | Type | Description                                           |
| :------------- | :--- | :---------------------------------------------------- |
| newick\_string | str  | A newick string representing the topology of the tree |

#### Internal Logic

The function uses a recursive approach to traverse the tree and build the newick string. It starts from the root node and recursively visits each child node. For each node, it checks if it is a leaf node. If it is, it appends the node name to the string. Otherwise, it recursively calls the function for each child node and encloses the results in parentheses. Branch lengths are added to the string if `record_branch_lengths` is set to True.