EnzyLand

EnzyLand profiles enzyme catalytic landscapes from enzyme sequence, substrate SMILES, pH, and temperature. The public inference code in this folder loads a fixed first-stage EnzyLand foundation model, extracts enzyme-substrate-environment representations, and applies second-stage samplers to predict log10-scale kcat, Km, and kcat/Km with confidence scores.

Input Format

The input CSV must contain at least these columns:

Column	Description
sequence	Amino-acid sequence. Multi-chain inputs can be separated by ;.
smiles	Substrate SMILES.
ph	pH. If missing in predict.py, it is filled with 7.0.
temperature	Temperature in Celsius. If missing in predict.py, it is filled with 30.0.

For sampler_finetune.py, training and few-shot CSV files should additionally contain:

Column	Description
category	Kinetic category. Public sampler fine-tuning uses kcat and km rows. Other categories are kept in intermediate files but skipped during sampler training.
log10value	Measured kinetic value in log10 units.

Installation

The code was checked in the following environment:

Package	Version
Python	3.10.18
numpy	1.26.4
pandas	1.5.3
torch	2.8.0+cu128
scikit-learn	1.5.1
scipy	1.15.3
matplotlib	3.10.6
tqdm	4.67.1
rdkit	2025.3.6
esm2	2.0.0

Example installation:

conda create -n enzyland python=3.10 -y
conda activate enzyland
pip install numpy==1.26.4 pandas==1.5.3 scipy==1.15.3 scikit-learn==1.5.1 matplotlib==3.10.6 tqdm==4.67.1 rdkit==2025.3.6 torch==2.8.0

EnzyLand also requires the esm2 package. Install it following the package instructions, for example from the ESM2 wheel source used by this project:

https://github.com/Y-H-Joe/esm2_whl

Checkpoints and Auxiliary Files

The default paths are script-relative:

ckpt/foundation_model/EnzyLand_foundation_model.pt
ckpt/sampler/EnzyLand_random_forest_kcat.pkl
ckpt/sampler/EnzyLand_random_forest_km.pkl
dict/protein_dict.pt
dict/ligand_dict.pt
EnzyLand_bins.txt

You can also pass absolute paths through the command line.

Inference

Run EnzyLand prediction on one CSV:

python predict.py \
  --data_dir example/Data_S1_independent_testset.csv.zip \
  --result_dir example/Data_S1_independent_testset.enzyland_pred.csv \
  --first_model_path ckpt/foundation_model/EnzyLand_foundation_model.pt \
  --second_kcat_model_path ckpt/sampler/EnzyLand_random_forest_kcat.pkl \
  --second_km_model_path ckpt/sampler/EnzyLand_random_forest_km.pkl \
  --bin_list EnzyLand_bins.txt \
  --method all_bin

Run EnzyLand prediction on multiple input files and write all outputs into one directory:

python predict.py \
  --data_dir data/file1.csv data/file2.csv \
  --result_dir outputs/enzyland_predictions

For large files, predict.py updates the protein and ligand dictionaries by chunks before inference:

python predict.py --data_dir large_input.csv --result_dir large_output.csv --read_chunksize 10000

The output columns are:

Output column	Description
Kcat_EnzyLand	Predicted log10(kcat).
Kcat_confidence	Sampler confidence for kcat.
Km_EnzyLand	Predicted log10(Km).
Km_confidence	Sampler confidence for Km.
Kcat_Km_EnzyLand	Predicted log10(kcat/Km), computed as log10(kcat)-log10(Km).
Kcat_Km_confidence	Average of kcat and Km confidence scores.

Few-Shot Sampler Fine-Tuning

sampler_finetune.py keeps the first-stage EnzyLand model fixed and fine-tunes the second-stage samplers. In the public workflow, the script trains two samplers:

• EnzyLand_<model_name>_kcat.pkl
• EnzyLand_<model_name>_km.pkl

kcat/Km is not trained as a separate sampler. During inference, predict.py computes:

log10(kcat/Km) = log10(kcat) - log10(Km)

What the Script Does

1. Reads the base training, validation, and test CSV files.
2. Optionally appends an augmented few-shot CSV to the base training set.
3. Updates protein and ligand feature dictionaries if new sequences or SMILES are found.
4. Extracts first-stage EnzyLand features for sampler training.
5. Trains separate kcat and Km second-stage samplers.
6. Writes trained sampler checkpoints and diagnostic plots.

Feature extraction is required for sampler training, but it is cached. If a matching .add_feat.pkl file already exists and is newer than the source CSV, the script reuses it instead of recomputing first-stage features.

Minimal Fine-Tuning Command

The recommended practice is to pass all important paths explicitly:

python sampler_finetune.py \
  --train_csv data/EnzyLand_train.csv \
  --test_csv data/EnzyLand_test.csv \
  --val_csv data/EnzyLand_val.csv \
  --few_shot_csv example/few_shot.csv \
  --augmented_few_shot_csv outputs/few_shot.augment.csv \
  --result_dir outputs/few_shot_sampler \
  --first_model_path ckpt/foundation_model/EnzyLand_foundation_model.pt \
  --prot_dict_dp dict/protein_dict.pt \
  --ligand_dict_dp dict/ligand_dict.pt \
  --bin_list EnzyLand_bins.txt \
  --model_name random_forest \
  --model_type bin_transfer \
  --few_shot_sample_weight 1.0

The few_shot.csv file should use the same column names as the training CSV. At minimum, it should contain:

sequence, smiles, ph, temperature, category, log10value

Only category == kcat and category == km rows are used to train samplers. ki rows and direct kcat_km rows are ignored by the public sampler fine-tuning script.

Fine-Tuning Without Few-Shot Data

To train samplers only from the provided base training set, disable few-shot adaptation:

python sampler_finetune.py \
  --train_csv data/EnzyLand_train.csv \
  --test_csv data/EnzyLand_test.csv \
  --val_csv data/EnzyLand_val.csv \
  --use_few_shot 0 \
  --result_dir outputs/base_sampler_refit

Useful Fine-Tuning Options

Option	Description
--model_name	Sampler model family. Default: random_forest.
--model_type	bin_transfer, classifier, or regressor. Default: bin_transfer.
--few_shot_target_n	Target size after few-shot augmentation. <=0 uses the automatic rule.
--few_shot_sample_weight	Relative sampling weight of few-shot rows during sampler training.
--mask_rate	Maximum amino-acid masking rate used during few-shot augmentation.
--ph_temp_perturb	Relative perturbation range for pH and temperature.
--kcat_y_perturb	Relative label perturbation for kcat, applied in linear space and converted back to log10.
--km_y_perturb	Relative label perturbation for Km, applied in linear space and converted back to log10.
--seed	One seed, or one seed per few-shot/result pair.

Five-Fold or Multi-Run Fine-Tuning

For multiple fine-tuning runs, pass matching lists to --few_shot_csv, --augmented_few_shot_csv, --result_dir, and optionally --seed. The script maps them one-to-one:

python sampler_finetune.py \
  --train_csv data/EnzyLand_train.csv \
  --test_csv data/EnzyLand_test.csv \
  --val_csv data/EnzyLand_val.csv \
  --few_shot_csv fold1_fewshot.csv fold2_fewshot.csv fold3_fewshot.csv \
  --augmented_few_shot_csv outputs/fold1.augment.csv outputs/fold2.augment.csv outputs/fold3.augment.csv \
  --result_dir outputs/fold1_sampler outputs/fold2_sampler outputs/fold3_sampler \
  --seed 41 42 43

Fine-Tuning Outputs

Each --result_dir contains:

Output	Description
EnzyLand_<model_name>_kcat.pkl or .pt	Fine-tuned kcat sampler.
EnzyLand_<model_name>_km.pkl or .pt	Fine-tuned Km sampler.
*.add_feat.pkl	Cached first-stage feature files for train/test/validation CSVs.
<model_name>_scatter_train_ratio_<ratio>.pdf	Measured-vs-predicted scatter plot with metrics.
<model_name>_calibration_train_ratio_<ratio>.pdf	Confidence calibration plot.

For random_forest with bin_transfer, the checkpoints are:

outputs/few_shot_sampler/EnzyLand_random_forest_kcat.pkl
outputs/few_shot_sampler/EnzyLand_random_forest_km.pkl

Use Fine-Tuned Samplers for Inference

Pass the fine-tuned sampler paths to predict.py:

python predict.py \
  --data_dir example/Data_S1_independent_testset.csv.zip \
  --result_dir outputs/few_shot_predictions.csv \
  --first_model_path ckpt/foundation_model/EnzyLand_foundation_model.pt \
  --second_kcat_model_path outputs/few_shot_sampler/EnzyLand_random_forest_kcat.pkl \
  --second_km_model_path outputs/few_shot_sampler/EnzyLand_random_forest_km.pkl \
  --bin_list EnzyLand_bins.txt \
  --method all_bin

Notes

• Kinetic predictions are in log10 units.
• kcat is expected in s^-1, Km and Ki in mM, and temperature in Celsius.
• The default all_bin inference mode uses the probability-weighted average over all bins. Use --method max_bin to use the most probable bin midpoint.