Landscapy

Landscapy is a Python package for constructing and analysing graph-based fitness landscapes. It supports sequence-aware graph construction, layered fitness and annotation data, landscape models and ruggedness and epistasis analyses, with use cases in sequence similarity network analysis and protein engineering. Landscapy supports a generic interface to deep learning packages, maintained in landscapy-ml.

Requirements and installation

Landscapy supports Python 3.11 and 3.12.

The default installation includes every user-facing feature in the all and ml dependency groups, together with a compatible 1.x release of landscapy-ml:

python -m pip install landscapy

For development from a checkout:

python -m pip install -e ".[dev]"
python -m pytest

See Installation and system requirements for more information on requirements and installation.

Command-line interface and quickstart

landscapy --help

Given an aligned protein FASTA file (sequences.fasta), a minimal portable kNN CLI workflow is:

landscapy knn-landscape \
  --sequences sequences.fasta \
  --output landscape.pkl \
  --k 5 \
  --backend balltree \
  --embedding-domain ohe

The equivalent Python code is:

from pathlib import Path

from fitness_landscape import FitnessLandscape, create_knn_graph
from fitness_landscape.core.graph import _encode_multiallele
from fitness_landscape.utils import fasta_to_prot20_sequences

sequences, aligned_sequences = fasta_to_prot20_sequences(
    "sequences.fasta",
    strict=False,
    return_gapped=True,
)
embedding_sequences = (
    aligned_sequences if aligned_sequences is not None else sequences
)
embeddings, _ = _encode_multiallele(embedding_sequences)

graph = create_knn_graph(
    sequences=sequences,
    k=5,
    embeddings=embeddings,
    embedding_domain="ohe",
    backend="balltree",
    _compute_hamming_edges=True,
)
landscape = FitnessLandscape.from_graph(
    graph,
    embeddings={"ohe": embeddings},
    active_embedding_domain="ohe",
)
landscape.save(Path("landscape.pkl"))

Cookbook

The worked-example cookbook provides examples for common Landscapy usage. Every recipe states its assumptions, expected outputs, and limits of interpretation. Short recipe examples are checked in CI; the networked end-to-end tutorial is run manually.

• Tutorial: constructing and analysing an SSN
• Tutorial: Quantitative analysis of an SSN
• Tutorial: ML training and inference on an SSN
• Installation and system requirements
• Foundations
• Components, topology, and annotated groups
• Graph construction and representation choice
• Saving, sharing, CLI use, and external visualization
• Ruggedness, autocorrelation, and spectral analysis
• Adaptive walks, accessibility, basins, optima, and neutral networks
• Epistasis on complete, sampled, and categorical landscapes
• Statistical inference and robustness analysis
• Simulation models and known-answer validation
• Validated exports for downstream machine learning
• Scaling, backend selection, and reproducible execution

License

Landscapy is distributed under the MIT License. See LICENSE.