SimulationResult¶

Container returned by LZGraph.simulate(). Holds the generated sequences along with their exact log-probabilities and token counts, and optionally V/J gene annotations.

Quick Example¶

result = graph.simulate(1000, seed=42)

# Iterate as strings
for seq in result:
    print(seq)

# Access metadata
print(result.log_probs[:5])   # exact log P(gen) per sequence
print(result.n_tokens[:5])    # LZ76 token count per sequence

Attributes¶

Attribute	Type	Description
`sequences`	`list[str]`	Generated CDR3 strings
`log_probs`	`np.ndarray[float64]`	Exact log-probability of each sequence under the LZ-constrained model
`n_tokens`	`np.ndarray[uint32]`	Number of LZ76 subpattern tokens in each sequence's walk
`v_genes`	`list[str]` or `None`	V gene used for each sequence (only with `sample_genes=True` or explicit `v_gene`)
`j_genes`	`list[str]` or `None`	J gene used for each sequence (only with gene-constrained simulation)

Exact probabilities

Unlike many generative models, each simulated sequence carries its exact generation probability, the precise product of all transition probabilities along the walk. This is not an approximation, and it enables unbiased importance-sampling estimators for diversity and entropy.

Sequence Protocol¶

SimulationResult implements Python's sequence protocol, so you can use it like a list of strings:

result = graph.simulate(100, seed=42)

# Length
print(len(result))          # 100

# Indexing, returns the sequence string
first = result[0]           # 'CASSLEPSGGTDTQYF'

# Slicing, returns a new SimulationResult with aligned metadata
subset = result[:10]
print(len(subset))          # 10
print(subset.log_probs)     # first 10 log-probs

# Iteration, yields strings
for seq in result:
    print(seq)

# Membership
print('CASSLGIRRT' in result.sequences)

Working with Metadata¶

The log_probs and n_tokens arrays are aligned with sequences: index i in each corresponds to the same generated sequence:

import numpy as np

result = graph.simulate(10000, seed=42)

# Find the most probable generated sequence
best_idx = np.argmax(result.log_probs)
print(f"Most probable: {result[best_idx]}")
print(f"  log P = {result.log_probs[best_idx]:.4f}")
print(f"  tokens = {result.n_tokens[best_idx]}")

# Summary statistics
print(f"Mean log P: {result.log_probs.mean():.2f}")
print(f"Std log P:  {result.log_probs.std():.2f}")
print(f"Mean length: {np.mean([len(s) for s in result.sequences]):.1f}")
print(f"Mean tokens: {result.n_tokens.mean():.1f}")

Gene-Annotated Results¶

When simulation includes gene data (sample_genes=True or explicit v_gene/j_gene), the result includes gene annotations:

result = graph.simulate(100, sample_genes=True, seed=42)

for i in range(3):
    print(f"{result[i]:25s}  V={result.v_genes[i]}  J={result.j_genes[i]}")

If the simulation was not gene-constrained, v_genes and j_genes are None:

result = graph.simulate(100, seed=42)
print(result.v_genes)  # None

Filtering Results¶

Since all arrays are aligned, you can use NumPy boolean indexing to filter:

import numpy as np

result = graph.simulate(10000, seed=42)

# Keep only sequences with > median probability
median_lp = np.median(result.log_probs)
mask = result.log_probs > median_lp

high_prob_seqs = [s for s, m in zip(result.sequences, mask) if m]
high_prob_lps = result.log_probs[mask]
print(f"Kept {len(high_prob_seqs)} sequences above median log P")

# Keep only sequences of specific length
lengths = np.array([len(s) for s in result.sequences])
mask_15 = lengths == 15
seqs_15 = [s for s, m in zip(result.sequences, mask_15) if m]
print(f"{len(seqs_15)} sequences of length 15")