Metadata-Version: 2.4
Name: landscapy
Version: 1.0.0
Summary: Construction and analysis of graph-based fitness landscapes
Author: Barnabas Gall, Dana S. Matthews
Author-email: "Matthew A. Spence" <matthew.spence@anu.edu.au>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MA-Spence/landscapy
Project-URL: Issues, https://github.com/MA-Spence/landscapy/issues
Project-URL: Repository, https://github.com/MA-Spence/landscapy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: cogent3==2025.7.10a10
Requires-Dist: faiss-cpu>=1.11; platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "aarch64")
Requires-Dist: faiss-cpu>=1.11; platform_system == "Darwin" and platform_machine == "x86_64"
Requires-Dist: faiss-cpu>=1.11; platform_system == "Darwin" and platform_machine == "arm64"
Requires-Dist: faiss-cpu>=1.11; platform_system == "Windows" and (platform_machine == "AMD64" or platform_machine == "ARM64" or platform_machine == "x86_64" or platform_machine == "arm64")
Requires-Dist: gudhi>=3.11
Requires-Dist: landscapy-ml<2,>=1
Requires-Dist: networkx>=3.2
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.3
Requires-Dist: piqtree<0.8,>=0.6.1; python_version < "3.12"
Requires-Dist: piqtree>=0.6.1; python_version >= "3.12"
Requires-Dist: pyarrow>=17
Requires-Dist: ray>=2.48
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: softalign>=1.0.0
Requires-Dist: torch>=2.1
Requires-Dist: torch-geometric>=2.6
Requires-Dist: transformers>=4.53.2
Requires-Dist: tqdm>=4.66
Provides-Extra: parquet
Requires-Dist: pyarrow>=17; extra == "parquet"
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == "cli"
Provides-Extra: knn
Requires-Dist: scikit-learn>=1.3; extra == "knn"
Provides-Extra: tda
Requires-Dist: gudhi>=3.11; extra == "tda"
Requires-Dist: scikit-learn>=1.3; extra == "tda"
Provides-Extra: analysis
Requires-Dist: gudhi>=3.11; extra == "analysis"
Requires-Dist: scikit-learn>=1.3; extra == "analysis"
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "aarch64")) and extra == "faiss"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Darwin" and platform_machine == "x86_64") and extra == "faiss"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "faiss"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Windows" and (platform_machine == "AMD64" or platform_machine == "ARM64" or platform_machine == "x86_64" or platform_machine == "arm64")) and extra == "faiss"
Requires-Dist: scikit-learn>=1.3; extra == "faiss"
Provides-Extra: parallel
Requires-Dist: ray>=2.48; extra == "parallel"
Provides-Extra: alignment
Requires-Dist: softalign>=1.0.0; extra == "alignment"
Provides-Extra: phylogeny
Requires-Dist: cogent3==2025.7.10a10; extra == "phylogeny"
Requires-Dist: piqtree<0.8,>=0.6.1; python_version < "3.12" and extra == "phylogeny"
Requires-Dist: piqtree>=0.6.1; python_version >= "3.12" and extra == "phylogeny"
Requires-Dist: softalign>=1.0.0; extra == "phylogeny"
Provides-Extra: ml
Requires-Dist: torch>=2.1; extra == "ml"
Requires-Dist: torch-geometric>=2.6; extra == "ml"
Requires-Dist: transformers>=4.53.2; extra == "ml"
Requires-Dist: tqdm>=4.66; extra == "ml"
Provides-Extra: embeddings
Requires-Dist: torch>=2.1; extra == "embeddings"
Requires-Dist: transformers>=4.53.2; extra == "embeddings"
Requires-Dist: tqdm>=4.66; extra == "embeddings"
Provides-Extra: all
Requires-Dist: click>=8.1; extra == "all"
Requires-Dist: cogent3==2025.7.10a10; extra == "all"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "aarch64")) and extra == "all"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Darwin" and platform_machine == "x86_64") and extra == "all"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "all"
Requires-Dist: faiss-cpu>=1.11; (platform_system == "Windows" and (platform_machine == "AMD64" or platform_machine == "ARM64" or platform_machine == "x86_64" or platform_machine == "arm64")) and extra == "all"
Requires-Dist: gudhi>=3.11; extra == "all"
Requires-Dist: piqtree<0.8,>=0.6.1; python_version < "3.12" and extra == "all"
Requires-Dist: piqtree>=0.6.1; python_version >= "3.12" and extra == "all"
Requires-Dist: pyarrow>=17; extra == "all"
Requires-Dist: ray>=2.48; extra == "all"
Requires-Dist: scikit-learn>=1.3; extra == "all"
Requires-Dist: softalign>=1.0.0; extra == "all"
Requires-Dist: torch>=2.1; extra == "all"
Requires-Dist: transformers>=4.53.2; extra == "all"
Requires-Dist: tqdm>=4.66; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: matplotlib>=3.8; extra == "dev"
Requires-Dist: numpydoc>=1.8; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=6; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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](https://github.com/MA-Spence/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`:

```bash
python -m pip install landscapy
```

For development from a checkout:

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

See [Installation and system requirements](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/installation/README.md) for more information on requirements and installation.

## Command-line interface and quickstart

```bash
landscapy --help
```

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

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

The equivalent Python code is:

```python
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](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/README.md) 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](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/tutorial-constructing-and-analysing-an-ssn.md)
- [Tutorial: Quantitative analysis of an SSN](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/tutorial-quantitative-analysis-of-an-ssn.md)
- [Tutorial: ML training and inference on an SSN](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/tutorial-ml-training-and-inference-on-an-ssn.md)
- [Installation and system requirements](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/installation/README.md)
- [Foundations](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/foundations/README.md)
- [Components, topology, and annotated groups](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/topology/README.md)
- [Graph construction and representation choice](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/graph-construction/README.md)
- [Saving, sharing, CLI use, and external visualization](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/io/README.md)
- [Ruggedness, autocorrelation, and spectral analysis](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/ruggedness/README.md)
- [Adaptive walks, accessibility, basins, optima, and neutral networks](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/accessibility/README.md)
- [Epistasis on complete, sampled, and categorical landscapes](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/epistasis/README.md)
- [Statistical inference and robustness analysis](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/statistics/README.md)
- [Simulation models and known-answer validation](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/simulation/README.md)
- [Validated exports for downstream machine learning](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/ml/README.md)
- [Scaling, backend selection, and reproducible execution](https://github.com/MA-Spence/landscapy/blob/main/docs/cookbook/scaling/README.md)

## License

Landscapy is distributed under the MIT License. See [LICENSE](LICENSE).
