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

# map_utils.py

## High-level description

This code defines a function `map_intbcs` that processes a molecule table to resolve allele ambiguity for each cellBC/intBC pair. It identifies the most frequent allele based on read count and UMI count, then filters out alignments with other alleles for each pair.

## Symbols

### `map_intbcs`

#### Description

This function takes a molecule table as input and returns a modified allele table where each cellBC/intBC pair is associated with a single allele. It achieves this by grouping the input table by cellBC, intBC, and allele, then selecting the allele with the highest read count (and UMI count as a tie-breaker) for each group. Alignments with other alleles for the same cellBC/intBC pair are removed.

#### Inputs

| Name            | Type             | Description                                                                        |
| :-------------- | :--------------- | :--------------------------------------------------------------------------------- |
| molecule\_table | pandas.DataFrame | A molecule table containing cellBC, intBC, allele, readCount, and UMI information. |

#### Outputs

| Name          | Type             | Description                                                                              |
| :------------ | :--------------- | :--------------------------------------------------------------------------------------- |
| mapped\_table | pandas.DataFrame | A modified allele table where each cellBC/intBC pair is associated with a single allele. |

#### Internal Logic

1. Drops rows with missing `intBC` values from the input `molecule_table`.
2. Groups the remaining rows by `cellBC`, `intBC`, and `allele`.
3. Aggregates the groups by summing `readCount` and counting `UMI`.
4. Sorts the aggregated table first by `UMI` in descending order, then by `readCount` in descending order.
5. Identifies duplicate `cellBC`/`intBC` pairs, keeping only the first occurrence (which corresponds to the highest read and UMI count).
6. Creates a set of tuples representing the selected `cellBC`, `intBC`, and `allele` combinations.
7. Filters the original `molecule_table` to keep only rows where the `cellBC`, `intBC`, and `allele` combination exists in the set created in step 6.
8. Logs the number of removed alleles and UMIs during the filtering process.
9. Returns the filtered `molecule_table`.

## References

* `logger`: Used for logging debug messages. Imported from `cassiopeia.mixins`.
* `utilities.log_molecule_table`: A decorator function used to log statistics of the molecule table before and after the function execution. Imported from `cassiopeia.preprocess`.

## Side Effects

* Logs debug messages indicating the number of alleles and UMIs removed during the filtering process.

## Performance Considerations

The function uses pandas groupby and apply operations, which can be computationally expensive for large datasets. Consider optimizing these operations or using alternative data structures if performance becomes a bottleneck.