msaframe 0.1.0
Lightweight MSA wrapper with position-aware slicing
Requires Python: >=3.10
Keywords: alignment, bioinformatics, msa, multiple sequence alignment, sequence

# MSAFrame

Lightweight Python library for working with Multiple Sequence Alignments. Query by residue position, not column index.

```python
from msaframe import MSAFrame, read_fasta

msa = MSAFrame({
    "human":  "MALW--KTGV",
    "mouse":  "MSLWGAKTGV",
    "fish":   "M-LWGA-TGV",
})

# "What's at position 3 in human across all species?"
msa.at("human", 3)  # {"human": "W", "mouse": "W", "fish": "W"}

# Slice by residue positions in a reference
msa.slice("human", 2, 6)  # {"human": "LW--K", "mouse": "LWGAK", "fish": "LWGA-"}
```

## The Problem

Alignment columns don't match residue positions. A mutation at "position 150" in your protein means nothing in a gapped alignment—is it column 150? 167? 183? It depends on where gaps fall upstream.

MSAFrame maintains bidirectional mappings between ungapped positions and alignment columns, so you can work in the coordinate system that matters: your reference sequence.

## Installation

```bash
pip install msaframe
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv pip install msaframe
```

**Zero dependencies.** Core functionality works with just Python 3.10+. Optional pandas/polars integration if you have them installed.

## Usage

### Creating an MSAFrame

From a dictionary:

```python
from msaframe import MSAFrame

msa = MSAFrame({
    "seq1": "MALW--KTGV",
    "seq2": "MSLWGAKTGV",
    "seq3": "M-LWGA-TGV",
})
```

From a FASTA file:

```python
from msaframe import MSAFrame, read_fasta

seqs = read_fasta("alignment.fasta")
msa = MSAFrame(seqs)
```

### Position-Aware Queries

The core API lets you query by ungapped position in a reference sequence:

```python
# Get all residues at position 5 in the reference
msa.at("human", 5)  # {"human": "K", "mouse": "K", "fish": "T"}

# Slice positions 10-20 in the reference
msa.slice("human", 10, 20)

# Convert between positions and columns
col = msa.col("human", 5)   # ungapped position → alignment column
pos = msa.pos("human", col)  # alignment column → ungapped position (None if gap)
```

### Basic Operations

```python
# Sequence access
msa["human"]                    # gapped sequence
msa.seq("human")                # gapped sequence
msa.seq("human", ungapped=True) # without gaps

# Metadata
msa.ids           # list of sequence IDs
msa.width         # alignment width (columns)
len(msa)          # number of sequences
msa.length("human")  # ungapped length of a sequence

# Column access (by alignment column index)
msa.column(42)    # {"human": "K", "mouse": "R", ...}
```

### DataFrame Export

Convert to pandas or polars for further analysis:

```python
df = msa.to_pandas()  # rows = sequences, columns = positions
df = msa.to_polars()
```

Raises `ImportError` if the library isn't installed—no hard dependencies.

## CLI

MSAFrame includes a colorful terminal interface for exploring alignments interactively:

```bash
msaframe alignment.fasta
```

Or query directly from the command line:

```bash
# Show position 150 in BRCA1
msaframe alignment.fasta brca1:150

# Show positions 100-120
msaframe alignment.fasta brca1:100-120

# Multiple positions (useful for viewing mutations)
msaframe alignment.fasta brca1:95,130,185
```

### Interactive Mode

```
MSA Explorer
MSAFrame(150 seqs × 892 cols)

no ref> ref brca1
Reference: BRCA1_HUMAN (863 aa)

BRCA1_HUMAN> 150
BRCA1_HUMAN position 150 (column 167):
  BRCA1_HUMAN: K

  K (142): BRCA1_MOUSE, BRCA1_RAT, BRCA1_BOVIN, ...
  R (5): BRCA1_XENLA, BRCA1_XENTR, ...
  - (3): BRCA1_DANRE, ...

BRCA1_HUMAN> 140-160
```

Commands:
- `ref <name>` — Set reference sequence (fuzzy matching)
- `<pos>` or `pos <n>` — Show residues at position
- `<start>-<end>` or `slice 
 <e>` — Show a range
- `col <n>` — Show alignment column by index
- `seq <name>` — Show full sequence
- `find <query>` — Search sequence IDs
- `list` — List all sequences

The display uses Clustal X coloring: hydrophobic (blue), polar (green), positive (red), negative (magenta), and special residues (G=orange, P=yellow, C=pink).

## Design Philosophy

**BYOMSA (Bring Your Own MSA):** MSAFrame doesn't align sequences—use MAFFT, Clustal, MUSCLE, or whatever you prefer. MSAFrame works with the result.

**Zero Dependencies:** The core library is a single file with no required dependencies. pandas and polars are optional extras for DataFrame export.

**Position-Aware:** It's often easier to think in residue positions ("mutation at position 150") rather alignment columns. MSAFrame bridges that gap with efficient bidirectional mappings.

## API Reference

### MSAFrame

| Method | Description |
|--------|-------------|
| `MSAFrame(seqs, gap_char="-")` | Create from dict of `{id: sequence}` |
| `at(ref, pos)` | Get all residues at ungapped position `pos` in `ref` |
| `slice(ref, start, end)` | Slice by ungapped positions `[start, end)` in `ref` |
| `col(ref, pos)` | Convert ungapped position → alignment column |
| `pos(ref, col)` | Convert alignment column → ungapped position (or `None`) |
| `column(col)` | Get all residues at alignment column `col` |
| `seq(id, ungapped=False)` | Get sequence, optionally without gaps |
| `length(id)` | Ungapped length of a sequence |
| `to_pandas()` | Export as pandas DataFrame |
| `to_polars()` | Export as polars DataFrame |

### Properties

| Property | Description |
|----------|-------------|
| `ids` | List of sequence identifiers |
| `width` | Alignment width (number of columns) |

### Helpers

| Function | Description |
|----------|-------------|
| `read_fasta(path)` | Parse FASTA file → `dict[str, str]` |

## License

MIT