### CafePlotter Example Command

Source: https://github.com/moshi4/cafeplotter/blob/main/README.md

Example command to run CafePlotter using an example dataset, ignoring branch length for plotting.

```bash
cafeplotter -i ./examples/singlelambda -o ./singlelambda_plot --ignore_branch_length
```

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

### Install CafePlotter Package

Source: https://github.com/moshi4/cafeplotter/blob/main/README.md

Install the CafePlotter package using pip. Requires Python 3.8 or later.

```bash
pip install cafeplotter
```

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

### Initialize and Use CafeParser

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Initialize the CafeParser with a CAFE5 result directory to access parsed data. Use this to get lists of gene families, access ancestral state reconstruction trees, and retrieve gene family changes and branch probabilities.

```python
from cafeplotter import CafeParser

# Initialize parser with CAFE5 result directory
cp = CafeParser("./cafe5_results")

# Access parsed data
print(f"Total gene families: {len(cp.all_famid_list)}")
print(f"Significant families: {len(cp.signif_famid_list)}")

# Access ancestral state reconstruction trees
for famid, tree in cp.famid2asr_tree.items():
    print(f"Family {famid}: {tree}")

# Get gene family changes for a specific family
family_change = cp.famid2family_change["1"]
print(f"Changes per taxon: {family_change.taxonid2change}")

# Get branch probabilities
branch_prob = cp.famid2branch_prob["1"]
print(f"Probabilities: {branch_prob.taxonid2prob}")

# Write result summary to TSV file
cp.write_result_summary("output/result_summary.tsv")

# Get total expansion/contraction counts per taxon
expansion_counts = cp.get_taxonid2total_increase(only_signif=True)
contraction_counts = cp.get_taxonid2total_decrease(only_signif=True)
```

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

### CLI Batch Processing

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Command-line interface usage for processing CAFE5 results in batch mode.

```APIDOC
## CLI: cafeplotter

### Description
Batch processing tool for CAFE5 results.

### Options
- **-i, --indir** (string) - Required - CAFE5 result directory
- **-o, --outdir** (string) - Required - Output directory
- **--format** (string) - Optional - Image format: png, jpg, svg, pdf (Default: png)
- **--fig_height** (float) - Optional - Figure height per leaf node (Default: 0.5)
- **--fig_width** (float) - Optional - Figure width (Default: 8.0)
- **--dpi** (int) - Optional - Figure resolution (Default: 300)
```

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

### Basic CafePlotter Command

Source: https://github.com/moshi4/cafeplotter/blob/main/README.md

Run CafePlotter with input CAFE5 results directory and output directory.

```bash
cafeplotter -i [CAFE5 result directory] -o [Output directory]
```

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

### Execute CafePlotter CLI commands

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Run batch processing on CAFE5 results using the command line. Options allow for customization of figure dimensions, labels, and color schemes.

```bash
# Basic usage
cafeplotter -i ./cafe5_results -o ./output_plots

# With customization options
cafeplotter -i ./cafe5_results -o ./output_plots \
    --format pdf \
    --fig_height 0.6 \
    --fig_width 10 \
    --leaf_label_size 14 \
    --count_label_size 10 \
    --p_label_size 6 \
    --ignore_branch_length \
    --expansion_color darkred \
    --contraction_color darkblue \
    --dpi 300

# Show help
cafeplotter -h

# Show version
cafeplotter -v
```

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

### Import CafePlotter data classes

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Access dataclasses used for representing parsed CAFE5 data structures.

```python
from cafeplotter.cafeparser import (
    BranchProb,
    CladeResult,
    FamilyChange,
    FamilyCount,
    FamilyResult
)

# BranchProb: Branch probability data for a gene family
# Properties: famid, taxonid2prob

# CladeResult: Clade-level expansion/contraction counts
# Properties: taxonid, increase, decrease, increase_label, decrease_label

# FamilyChange: Gene count changes per taxon for a family
# Properties: famid, taxonid2change

# FamilyCount: Gene counts per taxon for a family
# Properties: famid, taxonid2count

# FamilyResult: Significance test results
# Properties: famid, pvalue, is_signif, display_pvalue
```

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

### Perform complete CAFE5 analysis workflow

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Parse CAFE5 results, generate summary plots, and create individual visualizations for significant gene families.

```python
from pathlib import Path
from cafeplotter import CafeParser, TreePlotter

# Parse CAFE5 results
cafe_dir = Path("./cafe5_results")
output_dir = Path("./plots")
output_dir.mkdir(exist_ok=True)

cp = CafeParser(cafe_dir)

# Create summary plot of all gene families
tp = TreePlotter(
    cp.asr_trees[0],
    height=0.5,
    width=8,
    ignore_branch_length=True
)

for clade_result in cp.clade_results:
    label = f"{clade_result.increase_label} / {clade_result.decrease_label}"
    tp.text_on_node(clade_result.taxonid, label, size=8)

tp.set_title("Summary of All Gene Family Changes")
tp.savefig(output_dir / "summary.png", dpi=300)

# Create individual plots for significant families
for famid in cp.signif_famid_list:
    tree = cp.famid2asr_tree[famid]
    tp = TreePlotter(tree, ignore_branch_length=True)

    taxonid2count = cp.famid2family_count[famid].taxonid2count
    taxonid2change = cp.famid2family_change[famid].taxonid2change

    for taxonid, count in taxonid2count.items():
        change = taxonid2change[taxonid]
        color = "red" if change > 0 else "blue" if change < 0 else "black"
        tp.text_on_node(taxonid, str(count), color=color)

    pvalue = cp.famid2family_result[famid].display_pvalue
    tp.set_title(f"Family {famid} (p={pvalue})")
    tp.savefig(output_dir / f"{famid}_family.png", dpi=300)

# Export summary data
cp.write_result_summary(output_dir / "result_summary.tsv")
```

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

### Initialize and Use TreePlotter

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Initialize TreePlotter with tree data and customize visualization parameters. This class allows adding text annotations, highlighting clades, setting titles, and updating plot properties before generating the figure.

```python
from cafeplotter import TreePlotter

# Create tree plotter from a tree file or BioPython Tree object
tp = TreePlotter(
    tree="tree.newick",              # Tree file or Tree object
    format="newick",                  # Tree format
    height=0.5,                       # Height per leaf node
    width=8,                          # Figure width
    ignore_branch_length=True,        # Use ultrametric tree
    leaf_label_size=12,               # Size of leaf labels
    innode_label_size=0               # Size of internal node labels
)

# Add text annotations on nodes
tp.text_on_node("human", "+50 / -30", size=8)
tp.text_on_node("mouse", "+25 / -45", size=8, color="red")

# Add arbitrary text at specific coordinates
tp.text(x=5.0, y=2.0, s="Custom annotation", size=10)

# Highlight a clade (MRCA of specified nodes)
tp.highlight(["human", "chimp"], color="yellow", alpha=0.3)

# Set figure title
tp.set_title("Gene Family Evolution")

# Update tree line properties
tp.update_plot_props(tree_line_kws=dict(color="gray", lw=0.5))

# Generate and save figure
fig = tp.plotfig(dpi=300)
tp.savefig("output/tree_plot.png", dpi=300)
```

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

### TreePlotter Methods

Source: https://context7.com/moshi4/cafeplotter/llms.txt

Core methods available in the TreePlotter class for customizing and exporting phylogenetic tree visualizations.

```APIDOC
## TreePlotter Methods

### Description
Methods for manipulating and exporting matplotlib-based tree figures.

### Methods
- **plotfig(dpi, ax)** - Generate matplotlib Figure object
- **savefig(savefile, dpi, pad_inches)** - Save figure to file (png, jpg, svg, pdf)
- **text(x, y, s, **kwargs)** - Add text at specific coordinates
- **text_on_node(node_name, text, **kwargs)** - Add text annotation on a tree node
- **highlight(node_names, color, **kwargs)** - Highlight a clade with a colored rectangle
- **set_title(label, **kwargs)** - Set figure title
- **update_plot_props(tree_line_kws)** - Update tree line styling
```

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

### CafeParser Class Usage

Source: https://context7.com/moshi4/cafeplotter/llms.txt

The CafeParser class is used to parse CAFE5 output files and access gene family data. It provides access to lists of gene families, mappings of family IDs to tree structures, branch probabilities, and gene count changes.

```APIDOC
## CafeParser Class

The `CafeParser` class is the primary interface for parsing CAFE5 output files. It automatically detects and parses all required result files from a CAFE5 output directory.

### Initialization
```python
from cafeplotter import CafeParser

# Initialize parser with CAFE5 result directory
cp = CafeParser("./cafe5_results")
```

### Key Properties

| Property | Type | Description |
|----------|------|-------------|
| `all_famid_list` | `list[str]` | List of all gene family IDs |
| `signif_famid_list` | `list[str]` | List of statistically significant gene family IDs |
| `taxonid_list` | `list[str]` | List of taxon IDs from clade results |
| `famid2asr_tree` | `dict[str, Tree]` | Mapping of family ID to BioPython Tree object |
| `famid2branch_prob` | `dict[str, BranchProb]` | Mapping of family ID to branch probabilities |
| `famid2family_change` | `dict[str, FamilyChange]` | Mapping of family ID to gene count changes |
| `famid2family_count` | `dict[str, FamilyCount]` | Mapping of family ID to gene counts |
| `famid2family_result` | `dict[str, FamilyResult]` | Mapping of family ID to significance results |

### Example Usage

```python
# Access parsed data
print(f"Total gene families: {len(cp.all_famid_list)}")
print(f"Significant families: {len(cp.signif_famid_list)}")

# Access ancestral state reconstruction trees
for famid, tree in cp.famid2asr_tree.items():
    print(f"Family {famid}: {tree}")

# Get gene family changes for a specific family
family_change = cp.famid2family_change["1"]
print(f"Changes per taxon: {family_change.taxonid2change}")

# Get branch probabilities
branch_prob = cp.famid2branch_prob["1"]
print(f"Probabilities: {branch_prob.taxonid2prob}")

# Write result summary to TSV file
cp.write_result_summary("output/result_summary.tsv")

# Get total expansion/contraction counts per taxon
expansion_counts = cp.get_taxonid2total_increase(only_signif=True)
contraction_counts = cp.get_taxonid2total_decrease(only_signif=True)
```
```

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

### TreePlotter Class Usage

Source: https://context7.com/moshi4/cafeplotter/llms.txt

The TreePlotter class is used for visualizing phylogenetic trees with customizable labels, highlights, and annotations. It can generate and save figures in various formats.

```APIDOC
## TreePlotter Class

The `TreePlotter` class handles phylogenetic tree visualization with support for customizable labels, highlights, and annotations.

### Initialization

```python
from cafeplotter import TreePlotter

# Create tree plotter from a tree file or BioPython Tree object
tp = TreePlotter(
    tree="tree.newick",              # Tree file or Tree object
    format="newick",                  # Tree format
    height=0.5,                       # Height per leaf node
    width=8,                          # Figure width
    ignore_branch_length=True,        # Use ultrametric tree
    leaf_label_size=12,               # Size of leaf labels
    innode_label_size=0               # Size of internal node labels
)
```

### Customization Methods

```python
# Add text annotations on nodes
tp.text_on_node("human", "+50 / -30", size=8)
tp.text_on_node("mouse", "+25 / -45", size=8, color="red")

# Add arbitrary text at specific coordinates
tp.text(x=5.0, y=2.0, s="Custom annotation", size=10)

# Highlight a clade (MRCA of specified nodes)
tp.highlight(["human", "chimp"], color="yellow", alpha=0.3)

# Set figure title
tp.set_title("Gene Family Evolution")

# Update tree line properties
tp.update_plot_props(tree_line_kws=dict(color="gray", lw=0.5))
```

### Figure Generation

```python
# Generate and save figure
fig = tp.plotfig(dpi=300)
tp.savefig("output/tree_plot.png", dpi=300)
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.