Thyme-1

Proteome-aware protein redesign for reducing predicted immunogenicity while preserving target protein constraints.

thyme combines a personalized or reference proteome with structure-conditioned sequence design. It builds a proteome k-mer graph, runs LigandMPNN on a target structure, decodes proteome-constrained candidate sequences, and scores the results with sequence, optional structure, and optional MHC-binding metrics.

This project was developed under the working name single-human-izer; the public release is named thyme.

Manuscript

The manuscript PDF, as well as manuscript files, figure-generation notebooks, and processed result tables, are distributed as GitHub Release assets rather than committed to the main repository.

• Download the latest manuscript PDF [6.5 MiB]
• Download the latest manuscript source and results archive [184 MB]

Author Contributions

E.F.X. Byrne conceptualized the study, designed and implemented the Thyme-1 pipeline, curated datasets, performed computational experiments, analyzed results, generated figures, and drafted the manuscript. S. Pillay reviewed the code and methodologies, evaluated the theoretical basis of the graph construction and decoding strategy, contributed to interpretation of the algorithmic approach, and reviewed the manuscript. All authors approved the final manuscript.

Contents

• Manuscript
• Installation
• Quickstart
• How It Works
• Configuration
• Outputs
• Common Workflows
• Documentation
• Repository Layout

Installation

Clone the repository and install the Python package:

git clone https://github.com/eamonbyrne/thyme.git
cd thyme
pip install -e ".[dev]"

The main pipeline expects LigandMPNN for structure-conditioned sequence probabilities. The helper script can install the external tools used by the default workflows:

DOWNLOAD_LIGANDMPNN_MODELS=1 bash scripts/setup_external_tools.sh

For genome-derived proteomes, install the required command-line tools:

apt-get -y install samtools bcftools tabix

See docs/external-tools.md for pinned forks, isolated virtual environments, MHCnuggets, and structure-prediction backends.

Quickstart

Run the small example config from the repository root:

thyme --config pipelines/thyme/configs/example.yaml

Equivalent wrapper:

python run_thyme.py --config pipelines/thyme/configs/example.yaml

The example uses a dummy proteome and disables expensive optional metrics by default. Edit the config before running on a real target/proteome pair.

How It Works

The thyme workflow has four stages:

1. prepare_proteome_graph: resolve a proteome source, generate k-mer counts, build a de Bruijn graph, and cache an ANN index over graph nodes.
2. prepare_target_protein: fetch or prepare the target structure, run LigandMPNN, and optionally combine structure-derived probabilities with activity/fixed-residue information.
3. run_decoder: select graph start nodes and decode proteome-constrained full-length candidate sequences.
4. run_metrics: save decoded outputs and compute sequence metrics, with optional structure and immunogenicity metrics.

The central question is: what protein sequence best satisfies the target protein constraints while using k-mers that already occur in the configured proteome?

For more background on the graph representation and decoding model, see docs/concept.md.

Configuration

A minimal config looks like:

output:
  base_dir: data/thyme/

proteome:
  source: dummy          # dummy | reference | fasta | genome
  graph:
    primary_k: 9
    other_ks: [10, 11]
    other_k_bonus: 0.2
    lambda_edge: 0.1

target_protein:
  structuredb_id: 1crn
  ligandmpnn:
    python_binary: python
    model_type: protein_mpnn
    seed: 123
    temperature: 0.2
    chains_to_design: [A]
    parse_these_chains_only: [A]
    batch_size: 1
    number_of_batches: 1

decoder:
  num_start_nodes: 5
  num_final_seqs_per_start_node: 5
  beam_width: 10
  top_k_ann: 100

metrics:
  immunogenicity:
    enabled: false
  structure:
    enabled: false
    compute_tm_score: false

Proteome sources:

• dummy: fetches a consensus human proteome and generates a mutated dummy proteome.
• reference: uses the unmutated consensus human proteome.
• fasta: uses proteome.proteome_fasta_path.
• genome: runs genome2proteome using proteome.genome2proteome.

See pipelines/thyme/configs/example.yaml and docs/configuration.md for more options.

Outputs

By default, outputs are written under output.base_dir, usually data/thyme/ or outputs/thyme/.

Important outputs include:

• results/<run_id>/output_sequences/: decoded FASTA and raw decoded sequence tables.
• results/<run_id>/output_sequences_metrics/: per-run metrics CSVs.
• results/<run_id>/output_sequences_metrics/finalists.csv: final selected candidates when final selection is enabled.
• results/<run_id>/ctx_snapshots/: lightweight stage snapshots for resume workflows.
• cache/: proteome FASTA, k-mer counts, graph artifacts, and ANN index files.

Common Workflows

Run selected stages:

thyme \
  --config pipelines/thyme/configs/example.yaml \
  --stages prepare_target_protein

Resume from a context snapshot:

thyme \
  --config pipelines/thyme/configs/example.yaml \
  --load-ctx data/thyme/results/<run_id>/ctx_snapshots/<snapshot>.json \
  --stages run_decoder,run_metrics

Run batch mode:

thyme-batch generate-manifest \
  --base-config pipelines/thyme/batch_setup/batch_example/example_base_config.yaml \
  --targets pipelines/thyme/batch_setup/batch_example/targets_tiny.csv \
  --proteomes pipelines/thyme/batch_setup/batch_example/proteomes_tiny.csv \
  --batch-root /tmp/thyme_batch

thyme-batch run \
  --manifest /tmp/thyme_batch/manifest.csv \
  --max-workers 4 \
  --resume

thyme-batch summarize \
  --manifest /tmp/thyme_batch/manifest.csv

Build a personalized proteome directly:

genome2proteome \
  --config pipelines/genome2proteome/configs/example.yaml \
  --external_save_dirpath /tmp/proteomes

Documentation

• docs/concept.md: biological motivation, de Bruijn graph representation, and decoding overview.
• docs/configuration.md: config sections and common examples.
• docs/metrics.md: sequence, structure, and immunogenicity metric definitions.
• docs/batch.md: batch manifests, execution, summaries, and W&B logging.
• docs/genome2proteome.md: personalized proteome synthesis from VCFs.
• docs/external-tools.md: external dependencies and optional backends.
• docs/troubleshooting.md: common failures and resume/cache notes.

Repository Layout

common/                         Shared path and config helpers
docs/                           Topic-specific documentation
pipelines/thyme/                Main thyme pipeline
pipelines/genome2proteome/      Genome-to-proteome helper pipeline
scripts/                        External tool setup helpers
tests/                          Unit tests
run_thyme.py                    Root Python wrapper for thyme
run_thyme_batch.py              Root Python wrapper for batch tools
run_genome2proteome.py          Root Python wrapper for genome2proteome
pyproject.toml                  Package metadata and console scripts

License

This project is licensed under the Apache License 2.0. See LICENSE.

Development

Run the test suite with:

pytest