> ## 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.

# compare.py

Here's a comprehensive documentation for the `compare.py` file in the `cassiopeia/critique` module:

## High-level description

This module provides functions for comparing two phylogenetic trees. It includes implementations for calculating the triplets correct accuracy and the Robinson-Foulds distance between two trees.

## Code Structure

The module contains two main functions: `triplets_correct` and `robinson_foulds`. These functions operate on `CassiopeiaTree` objects, which represent phylogenetic trees. The `triplets_correct` function is more complex, involving sampling and comparison of triplets at different depths of the trees, while the `robinson_foulds` function is a wrapper around the Ete3 library's implementation of the Robinson-Foulds distance.

## Symbols

### `triplets_correct`

#### Description

This function calculates the triplets correct accuracy between two trees. It samples triplets (sets of three leaves) at each depth of the tree and compares their topology between the two input trees.

#### Inputs

| Name                     | Type           | Description                                                             |
| :----------------------- | :------------- | :---------------------------------------------------------------------- |
| tree1                    | CassiopeiaTree | The first input tree                                                    |
| tree2                    | CassiopeiaTree | The second input tree to be compared                                    |
| number\_of\_trials       | int            | Number of triplets to sample at each depth (default: 1000)              |
| min\_triplets\_at\_depth | int            | Minimum number of triplets needed at a depth for inclusion (default: 1) |

#### Outputs

| Name                          | Type              | Description                                                   |
| :---------------------------- | :---------------- | :------------------------------------------------------------ |
| all\_triplets\_correct        | Dict\[int, float] | The proportion of all triplets correct at each depth          |
| resolvable\_triplets\_correct | Dict\[int, float] | The proportion of resolvable triplets correct at each depth   |
| unresolved\_triplets\_correct | Dict\[int, float] | The proportion of unresolvable triplets correct at each depth |
| proportion\_unresolvable      | Dict\[int, float] | The proportion of unresolvable triplets at each depth         |

#### Internal Logic

1. Initialize dictionaries to store results
2. Create copies of input trees and collapse unifurcations
3. Annotate tree depths and compute number of triplets at each depth
4. For each depth:
   * Sample triplets and compare their topology between the two trees
   * Calculate various statistics (all, resolvable, unresolved triplets correct)
5. Return the computed statistics

### `robinson_foulds`

#### Description

This function computes the Robinson-Foulds distance between two trees. It's a wrapper around the Ete3 library's implementation.

#### Inputs

| Name  | Type           | Description                          |
| :---- | :------------- | :----------------------------------- |
| tree1 | CassiopeiaTree | The first input tree                 |
| tree2 | CassiopeiaTree | The second input tree to be compared |

#### Outputs

| Name    | Type  | Description                                                   |
| :------ | :---- | :------------------------------------------------------------ |
| rf      | float | The Robinson-Foulds distance between the two trees            |
| rf\_max | float | The maximum possible Robinson-Foulds distance for these trees |

#### Internal Logic

1. Create copies of input trees and collapse unifurcations
2. Convert trees to Ete3 format
3. Compute Robinson-Foulds distance using Ete3's implementation
4. Return the distance and maximum possible distance

## Dependencies

| Dependency                              | Purpose                                                           |
| :-------------------------------------- | :---------------------------------------------------------------- |
| collections                             | Used for defaultdict                                              |
| copy                                    | Used for deep copying trees                                       |
| ete3                                    | Used for Robinson-Foulds distance calculation                     |
| networkx                                | Not directly used in this file, but likely used in CassiopeiaTree |
| numpy                                   | Used for numerical operations                                     |
| typing                                  | Used for type hinting                                             |
| cassiopeia.critique.critique\_utilities | Used for utility functions                                        |
| cassiopeia.data.CassiopeiaTree          | Used as the main data structure for trees                         |

## Error Handling

The code does not implement explicit error handling. It relies on the underlying libraries and data structures to raise appropriate exceptions.

This module provides essential functionality for comparing phylogenetic trees in the Cassiopeia project. The `triplets_correct` function offers a detailed comparison of tree topologies at different depths, while the `robinson_foulds` function provides a standard distance metric for tree comparison. These functions are likely used in various analysis and validation tasks within the larger Cassiopeia framework.