Metadata-Version: 2.4
Name: goeburst
Version: 1.0.0
Summary: goeBURST MLST Minimum Spanning Tree visualization
Author: WorkBuddy
License: MIT
Project-URL: Source Code, https://github.com/user/goeburst
Project-URL: Issue Tracker, https://github.com/user/goeburst/issues
Keywords: mlst,cgmlst,wgmlst,goeburst,eburst,minimum-spanning-tree,bioinformatics,microbiology,molecular-epidemiology,phyloviz
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: matplotlib>=3.5
Requires-Dist: networkx>=2.7
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# goeBURST

**MLST / cgMLST Minimum Spanning Tree visualization with goeBURST algorithm**

Implements the goeBURST algorithm (Francisco et al., 2009) — a refinement of eBURST (Feil et al., 2004) — to construct a globally-optimized Minimum Spanning Tree from multi-locus sequence typing data. Renders publication-quality figures with pie-chart nodes.

![Example MST](https://via.placeholder.com/800x600?text=goeBURST+MST)

## Installation

```bash
pip install goeburst
```

Or from source:

```bash
git clone <repo-url> && cd goeburst
pip install .
```

**Dependencies** (installed automatically): `numpy`, `matplotlib`, `networkx`.

## Quick Start

### Command line

```bash
goeburst -p profileData.tab -i isolateData.tab -g serotype -o mst.png
```

| Option | Description |
|--------|-------------|
| `-p, --profile` | Path to allele-profile table (TSV/CSV) |
| `-i, --isolates` | Path to isolate metadata (TSV/CSV) |
| `-g, --group` | Metadata column for pie-chart colouring |
| `-o, --output` | Output image path |
| `--figsize W H` | Figure size in inches (default: 18 14) |
| `--dpi` | Output resolution (default: 150) |
| `--format` | Force format: png, pdf, svg, jpg |

### Python API

```python
from goeburst import (
    parse_profile_data, parse_isolate_data, build_st_table,
    goeBURST_mst, plot_goeBURST,
)

# 1. Load data
profiles, loci = parse_profile_data("profileData.tab")
isolates, meta_cols = parse_isolate_data("isolateData.tab")

# 2. Build ST-level summary
st_profiles, st_counts, st_meta, all_cats, skipped = build_st_table(
    profiles, isolates, "serotype"
)

# 3. Run goeBURST algorithm
edges = goeBURST_mst(st_profiles)

# 4. Render plot
plot_goeBURST(
    st_profiles, st_counts, st_meta, all_cats, edges,
    group_col="serotype", output_path="mst.png",
)
```

## Input Format

### Profile data (`-p`)

Tab- or comma-separated file where each row is an isolate and each column is a locus:

```
FILE    aroE    gdh     gki     recP    spi     xpt     ddl
isolate1    1   1   2   2   6   1   6
isolate2    1   1   4   1   6   1   6
```

- First column: isolate identifier (must match FILE in isolate data)
- Remaining columns: integer allele numbers (0 = missing / unknown)

### Isolate data (`-i`)

```
FILE    ST  serotype    country
isolate1    1   O157    USA
isolate2    2   O104    DE
```

- Must contain: `FILE` (or `ID`) and `ST` columns
- Additional columns are available for pie-chart grouping

## Algorithm

The goeBURST algorithm produces a complete Minimum Spanning Tree using tiebreak rules that prioritise biologically meaningful links:

1. **Lower allelic distance** — SLV (1 locus) > DLV (2) > TLV (3) > …
2. **More SLV connections** — favour STs that are hubs of single-locus variants
3. **More DLV / TLV connections** — secondary / tertiary tiebreaks
4. **Lower ST identifier** — deterministic final tiebreak

The MST is built via Kruskal's algorithm on the sorted edge list.

## Edge Styles

| Distance | Style | Meaning |
|----------|-------|---------|
| 1 | Solid | Single-Locus Variant (SLV) |
| 2 | Dashed | Double-Locus Variant (DLV) |
| 3 | Dotted | Triple-Locus Variant (TLV) |
| >= 4 | Dash-dot | Higher-distance link |

## References

- Francisco AP, Vaz C, Monteiro PT, et al. (2009) Global optimal eBURST analysis of multilocus typing data using a graphic matroid approach. *BMC Bioinformatics*, 10:152.
- Feil EJ, Li BC, Aanensen DM, et al. (2004) eBURST: inferring patterns of evolutionary descent among clusters of related bacterial genotypes from multilocus sequence typing data. *Journal of Bacteriology*, 186:1518–1530.

## License

MIT
