Quick start

This page takes you from an installed BEAM to your first answer computed over every possible sequence. Every output below is what the code printed when this page was built.

Load the reference model.

BEAM comes with a model built from 38,538 human TCRβ repertoires. The first call downloads it (about 90 MB) and checks it; later calls load it from your disk.
load.py
```
import BEAM

model = BEAM.load_pretrained("human_tcrb_cdr3_aa_foundation")
print(model)
```
Output
```
BeamModel(order=4, sequences=926,909,993, states=194,481, memory=994MB)
```
Full program, including the set-up hidden here
The model has seen 926,909,993 distinct CDR3β sequences, and uses about 1 GB of memory.
Ask how likely a sequence is.

pseq gives the probability that one TCR drawn from this population has exactly that CDR3.
score.py
```
import BEAM

model = BEAM.load_pretrained("human_tcrb_cdr3_aa_foundation")

for cdr3 in ["CASSLGQGYEQYF", "CASSPGTGELFF", "CWWWWWWWWF"]:
    print(f"{cdr3:15} {model.pseq(cdr3):.3g}")
```
Output
```
CASSLGQGYEQYF   3.3e-05
CASSPGTGELFF    2.89e-05
CWWWWWWWWF      6.9e-23
```
Full program, including the set-up hidden here
The first two are typical CDR3s, with probabilities around 3 in 100,000. The last is implausible, and its probability says so: about 7 × 10⁻²³.
Draw new sequences.

sample draws sequences in proportion to their probability. The same seed gives the same sequences; give different seeds for independent draws (without one, the seed is 0).
sample.py
```
import BEAM

model = BEAM.load_pretrained("human_tcrb_cdr3_aa_foundation")

for cdr3 in model.sample(5, seed=1):
    print(cdr3)
```
Output
```
CASSPGTSSDTYEQYF
CASSLGTYSYNEQFF
CASRPGNSPLHF
CSVLKSGTPGEKLFF
SVGSGVNIGEQYF
```
Full program, including the set-up hidden here
Answer a sampling question without simulating.

If you sequence 100,000 TCRs from this population, how many different sequences will you see? BEAM computes the expected number directly, with a guaranteed bound on its error, instead of simulating.
depth.py
```
import BEAM
from BEAM.analytics.exact_occupancy import ExactOccupancy

model = BEAM.load_pretrained("human_tcrb_cdr3_aa_foundation")
occupancy = ExactOccupancy(model)

distinct = occupancy.richness(100_000)
print(f"distinct sequences in 100,000 TCRs: {distinct.value:,.0f}")
print(f"guaranteed relative error bound:   {distinct.bound:.2g}")
```
Output
```
distinct sequences in 100,000 TCRs: 96,771
guaranteed relative error bound:   4.6e-13
```
Full program, including the set-up hidden here
The first such question takes a minute or two while BEAM prepares the integrals it needs. After that, every depth is answered instantly.