David Medina-Ortiz1,,
Álvaro Olivera-Nappa1,
María Elena Lienqueo2,
Rafael Opazo3,
and Jaime Romero3,.
1Departamento de Ingeniería en Computación, Universidad de Magallanes, Avenida Bulnes 01855, 6210427, Punta Arenas, Chile.
2Centro de Biotecnología y Bioingeniería (CeBiB), Departamento de Ingeniería Química, Biotecnología y Materiales, Universidad de Chile, Av. Beauchef 851, 8370458, Santiago, Chile.
3Laboratorio de Biotecnología de Alimentos, Instituto de Nutrición y Tecnología de los Alimentos (INTA), Universidad de Chile, El Líbano 5524, Santiago 7830489, Chile.
*Corresponding authors: David Medina-Ortiz and Jaime Romero.
PhageLysData is an evidence-aware data resource for integrating, harmonizing, characterizing, and computationally enriching phage lytic proteins collected from heterogeneous public sources.
The resource organizes exact protein sequences into explicit evidence universes, preserves source-level provenance, separates non-predictive support from prediction-derived support, and provides reusable annotation, physicochemical, structural, and numerical-representation layers.
PhageLysData is a data resource and reproducible resource-construction workflow. It is not presented as a predictive model or as a definitive classifier of phage lytic proteins. Its primary purpose is to provide a harmonized, provenance-aware, evidence-aware, and computationally reusable foundation for downstream biological and machine-learning analyses.
The complete public data release is distributed separately through Zenodo. This GitHub repository contains the source-processing workflow, reproducible worked examples, and publication-facing Supplementary Information figure notebooks used to construct, inspect, reuse, and document the resource.
- Overview
- Resource at a glance
- Biological scope
- Evidence model and resource universes
- Main resource outputs
- Data availability and Zenodo
- Repository structure
- Software requirements
- Installation
- Reconstructing PhageLysData
- Worked examples
- Publication and Supplementary Information figures
- Quick start
- Reproducibility and traceability
- Citation
- License
- Contact
Public information on phage lytic proteins is distributed across general protein databases, specialized enzyme collections, phage genome resources, prediction-oriented repositories, and manually curated datasets. These sources differ substantially in sequence identifiers, biological terminology, annotation depth, evidence interpretation, prediction status, metadata completeness, and data structure.
PhageLysData addresses these limitations through a staged and auditable workflow that:
- retrieves and preserves source-specific records and provenance;
- standardizes protein sequences and source metadata;
- consolidates identical protein sequences through stable exact-sequence identifiers;
- separates non-predictive biological support from prediction-derived assertions;
- defines explicit resource universes and evidence Tiers;
- integrates frozen UniProtKB annotation information;
- performs homogeneous InterProScan-based functional enrichment across the Core;
- computes reusable physicochemical descriptors;
- links existing experimental PDB structures and retrievable AlphaFold DB models;
- distributes precomputed protein language model embeddings and one-hot representations;
- provides resource-level characterization tables;
- exposes reproducible worked examples for querying, visualization, clustering, classification, and candidate retrieval;
- provides publication-facing notebooks that regenerate Supplementary Information figures from frozen release or notebook outputs.
The stable identifier used throughout the resource is:
sequence_entity_id
Each sequence_entity_id corresponds to one exact normalized amino-acid sequence and is preserved across Core tables, annotation relations, physicochemical descriptors, structural assets, numerical representations, characterization outputs, and worked examples.
PhageLysData v1.0 integrates:
| Resource component | Entities / observations |
|---|---|
| Source observations | 807,366 |
| Exact-sequence entities | 759,105 |
| Core | 11,867 |
| Prediction Extension | 745,092 |
| Context | 2,146 |
The evidence-supported Core is further organized by evidence Tier:
| Evidence Tier | Core entities |
|---|---|
| Tier 1 | 90 |
| Tier 2 | 784 |
| Tier 3 | 9,836 |
| Tier 4 | 1,157 |
The deeply enriched Core includes:
| Asset / annotation layer | Core entities |
|---|---|
| UniProtKB-mapped entities | 7,347 |
| Any InterProScan match | 11,549 |
| InterPro annotation | 11,215 |
| Pfam annotation | 9,300 |
| GO annotation | 6,775 |
| Pathway annotation | 9,662 |
| Any existing structural asset | 745 |
| Representation-eligible / complete | 11,259 |
The public release additionally contains:
- physicochemical descriptors and sequence-level properties;
- UniProtKB relation tables;
- InterProScan, InterPro, Pfam, GO, and pathway relations;
- mapped PDB structural assets where available;
- retrievable AlphaFold DB models where available;
- 11 precomputed protein language model embedding matrices;
- one-hot sequence representations;
- resource characterization tables;
- manifests, provenance records, validation records, and SHA-256 checksums.
PhageLysData focuses on proteins associated with phage-mediated lytic activity and related host-envelope degradation.
The frozen biological ontology contains four non-exclusive target classes:
endolysindepolymerasevirion_associated_lytic_enzymeother_phage_envelope_lytic_enzyme
For Core-level summaries, an additional derived resource label is used:
multiple_nonexclusive
multiple_nonexclusive is not a fifth biological target class. It identifies Core entities supported by more than one non-predictive target class and prevents those entities from being forced into an artificial single-class assignment.
These labels are harmonized resource-level representations of source evidence. They should not be interpreted as replacements for detailed mechanistic, family-level, domain-level, or evolutionary classifications.
Source-specific biological terminology and provenance remain available so that users can inspect the evidence supporting each exact-sequence entity.
PhageLysData separates exact-sequence entities according to the evidence supporting their inclusion.
The Core contains entities with at least one valid non-predictive target assertion.
The Core is the principal deeply enriched and characterized resource. Prediction-derived assertions may coexist with Core membership but do not replace or override non-predictive support.
The Prediction Extension contains prediction-only candidates whose valid target assertions are exclusively prediction-derived.
These entities are retained for provenance, candidate-space coverage, and future reuse but remain separate from the evidence-supported Core.
The Context universe contains retained exact-sequence entities without a valid target assertion under the frozen resource ontology.
These records preserve source, genome, lysis-system, or other provenance and biological context.
Evidence Tiers apply only to Core entities.
| Tier | General interpretation |
|---|---|
Tier 1 |
Direct experimental support under the frozen evidence rules |
Tier 2 |
High-confidence curated or independently supported evidence |
Tier 3 |
Annotation-supported evidence |
Tier 4 |
Supported but ambiguous, incomplete, weakly resolved, or conflicting evidence |
Prediction Extension entities are never assigned Tier 1--4.
Resource-universe membership, canonical target class, and evidence Tier are frozen before downstream enrichment and are not modified by physicochemical analysis, annotation enrichment, structural linkage, numerical representation generation, characterization, clustering, or classification.
The public release is organized as:
PhageLysData_v1.0/
├── core/
├── prediction_extension/
├── context/
├── representations/
├── structures/
├── characterization/
├── metadata/
├── README.md
├── MANIFEST.tsv
└── CHECKSUMS.sha256
The principal Core table is:
core/phagelysdata_core.parquet
It contains one row per Core sequence_entity_id and integrates frozen resource metadata with availability flags for downstream assets.
Additional Core assets include:
core/
├── phagelysdata_core.parquet
├── phagelysdata_core.tsv.gz
├── phagelysdata_core.fasta.gz
├── phagelysdata_core_asset_availability.parquet
├── physicochemical/
└── annotations/
The release includes sequence-level physicochemical and descriptor tables such as:
core/physicochemical/
├── physicochemical_features.parquet
├── modlamp_descriptors.parquet
├── amino_acid_composition.parquet
├── molecular_formula.parquet
└── sequence_qc.parquet
core/annotations/uniprot/
This directory contains entity summaries, accession-level annotations, and relation tables for frozen UniProtKB-derived information.
core/annotations/interproscan/
This directory contains independently generated InterProScan relations, including member-database matches, InterPro entries, Pfam matches and architectures, GO terms, and pathway annotations.
InterProScan enrichment was generated with:
InterProScan 5.78-109.0
InterPro 109.0
Pfam 38.2
prediction_extension/phagelysdata_prediction_extension.parquet
This table contains prediction-only target entities kept outside the deeply enriched Core.
context/phagelysdata_context.parquet
This table preserves context/provenance entities retained by the integration workflow but lacking a valid target assertion under the frozen ontology.
structures/
├── structural_registry.parquet
├── structural_asset_manifest.parquet
├── ...
└── coordinates/
├── pdb/
└── alphafold/
Existing structural information is included when mapped PDB structures or retrievable AlphaFold DB models are available.
No additional structural prediction is performed as part of PhageLysData v1.0.
The no_existing_structure state therefore means that no successfully retrieved PDB or AlphaFold DB asset was available under the frozen release workflow; it does not assert universal absence from external databases.
representations/
├── representation_registry.parquet
├── representation_eligibility.parquet
├── one_hot/
└── plm/
PhageLysData v1.0 distributes 11 precomputed protein language model embedding matrices plus one-hot encoding for representation-eligible Core sequences.
The PLM matrices use a common representation contract:
- final hidden layer;
- mean sequence pooling;
- FP32 output;
- maximum eligible sequence length of 1,024 amino acids;
- canonical 20-amino-acid alphabet.
The representation layer includes models from the ESM-2, ESM-C, Ankh, ProtBERT, ProtT5, and Mistral-Prot families.
characterization/
This directory contains frozen descriptive characterization tables for:
- resource universes;
- evidence Tiers;
- canonical target classes;
- Tier-by-class composition;
- source and evidence richness;
- sequence-length and physicochemical distributions;
- functional annotation coverage;
- structural coverage;
- representation coverage;
- recurrent InterPro, Pfam, GO, and pathway annotations.
The complete, versioned PhageLysData v1.0 resource is archived on Zenodo:
DOI: https://doi.org/10.5281/zenodo.22046027
Version: v1.0
Repository: https://github.com/kren-ai-lab/phagelysdata
The Zenodo archive contains the frozen public data release only:
PhageLysData_v1.0/
├── core/
├── prediction_extension/
├── context/
├── representations/
├── structures/
├── characterization/
├── metadata/
├── README.md
├── MANIFEST.tsv
└── CHECKSUMS.sha256
The public release is the primary entry point for resource users and is the authoritative frozen dataset associated with version v1.0.
The larger construction workspace is intentionally not part of the Zenodo data release. Resource construction internally separates:
raw_data/
processed_data/
data_release/
| Layer | Purpose |
|---|---|
raw_data/ |
Frozen/native source packages and source snapshots used during construction |
processed_data/ |
Staged construction, enrichment, characterization, and validation history |
data_release/ |
Curated, portable, user-facing PhageLysData release |
Worked examples consume the public release only and do not require raw_data/ or processed_data/.
The archived release includes MANIFEST.tsv and CHECKSUMS.sha256 for asset inventory and integrity verification.
The repository separates resource construction, release-facing reuse workflows, frozen notebook outputs, and publication-facing figure generation.
.
├── src/
│ ├── uniprot_collection_data/
│ ├── PhaLP/
│ ├── INPHARED/
│ ├── DePP/
│ ├── DposFinder/
│ ├── DepoCatalog/
│ ├── PhagesDB/
│ ├── post_processing/
│ ├── data_enrichment/
│ ├── data_representation/
│ ├── data_integration/
│ ├── data_characterization/
│ └── data_release/
│
├── notebooks/
│ ├── README.md
│ ├── 00_getting_started.ipynb
│ ├── 01_resource_characterization.ipynb
│ ├── 02_embedding_space_v0_2.ipynb
│ ├── 03_clustering_example_v0_2.ipynb
│ ├── 04_classification_example.ipynb
│ └── 05_candidate_selection_v0_2.ipynb
│
├── notebook_outputs/
│ ├── 01_resource_characterization/
│ ├── 02_embedding_space/
│ ├── 03_clustering_example/
│ ├── 04_classification_example/
│ └── 05_candidate_selection/
│
├── si_figures/
│ ├── S02_physicochemical_properties_by_class.ipynb
│ ├── S03_annotation_asset_coverage.ipynb
│ ├── S04_embedding_space_figure.ipynb
│ ├── S05_hdbscan_clustering_figure.ipynb
│ ├── S06_supervised_classification_figure.ipynb
│ ├── S07_candidate_retrieval_figure.ipynb
│ └── generated/
│
├── CITATION.cff
├── environment.yml
├── LICENSE
├── README.md
└── .gitignore
| Directory | Description |
|---|---|
src/uniprot_collection_data/ |
UniProtKB query design, acquisition, hydration, evidence extraction, and source-layer closure |
src/PhaLP/ |
PhaLP source audit, extraction, normalization, evidence construction, and closure |
src/INPHARED/ |
INPHARED audit, extraction, normalization, candidate/evidence construction, and closure |
src/DePP/ |
DePP audit, retrieval, normalization, evidence construction, and closure |
src/DposFinder/ |
DposFinder audit, normalization, evidence construction, and closure |
src/DepoCatalog/ |
DepoCatalog source processing and closure |
src/PhagesDB/ |
PhagesDB source processing and closure |
src/post_processing/ |
Cross-source integration ontology, resource-universe definition, physicochemical descriptors, and UniProtKB enrichment |
src/data_enrichment/ |
InterProScan enrichment and existing-structure linkage |
src/data_representation/ |
PLM embedding generation, one-hot encoding, and representation-layer finalization |
src/data_integration/ |
Final Core/resource construction closure |
src/data_characterization/ |
Frozen descriptive resource characterization |
src/data_release/ |
Portable workspace organization and public-release materialization |
notebooks/ |
Release-facing worked examples demonstrating direct resource reuse; see notebooks/README.md |
notebook_outputs/ |
Frozen, lightweight outputs generated by worked examples and used where needed by publication-facing SI figures |
si_figures/ |
Publication-facing notebooks that regenerate Supplementary Information figures from the public release or frozen notebook outputs |
si_figures/generated/ |
Derived PDF/SVG/PNG figures and plotting tables produced by the SI figure notebooks |
notebook_outputs/ and si_figures/generated/ contain derived analytical outputs, not authoritative resource data. The authoritative biological and computational resource is the frozen Zenodo release.
A frozen repository-level environment.yml is provided for the public worked examples, publication-facing figure notebooks, and the principal Python-based reconstruction utilities.
The frozen environment includes:
- Python 3.13;
- pandas;
- NumPy;
- SciPy;
- PyArrow;
- Matplotlib;
- scikit-learn;
umap-learn;- IPython /
ipykernel; - JupyterLab / Notebook;
- Biopython;
- requests;
- lxml;
- openpyxl;
- PyYAML;
- psutil;
- tqdm;
- modlAMP 4.3.2;
- Java 11, Perl, wget, and curl for supporting reconstruction utilities.
The clustering example uses sklearn.cluster.HDBSCAN; a separate external hdbscan package is not required by the public notebook suite.
No GPU is required to execute the public worked examples or publication-facing SI figure notebooks because the required PLM representations are already distributed with the release.
Some construction stages rely on external or stage-specific software that is intentionally not bundled into the lightweight repository environment:
- InterProScan 5.78-109.0 with InterPro 109.0 and Pfam 38.2;
- Sylphy for PLM and one-hot representation generation;
- pretrained PLM checkpoints used during numerical-representation generation;
- access to source-specific external databases/services where applicable.
Some reconstruction stages require substantial storage, memory, CPU time, GPU resources, or external service access.
git clone https://github.com/kren-ai-lab/phagelysdata.git
cd phagelysdataconda env create -f environment.yml
conda activate phagelysdataRegister the environment as a Jupyter kernel if desired:
python -m ipykernel install --user \
--name phagelysdata \
--display-name "Python (PhageLysData)"Download and unpack the public release from:
https://doi.org/10.5281/zenodo.22046027
The resulting directory should contain:
PhageLysData_v1.0/
├── core/
├── prediction_extension/
├── context/
├── representations/
├── structures/
├── characterization/
├── metadata/
├── MANIFEST.tsv
└── CHECKSUMS.sha256
Either define:
export PHAGELYSDATA_ROOT=/path/to/PhageLysData_v1.0or set the explicit path near the top of a notebook:
from pathlib import Path
RELEASE_ROOT_OVERRIDE = Path("/path/to/PhageLysData_v1.0")The explicit override is often the most reliable option when running notebooks through VS Code or remote Jupyter kernels.
SI notebooks that regenerate embedding, clustering, classification, or candidate-retrieval figures use frozen tables under notebook_outputs/.
Optionally define:
export PHAGELYSDATA_NOTEBOOK_OUTPUTS=/path/to/phagelysdata/notebook_outputsEach SI notebook also provides an explicit *_ROOT_OVERRIDE variable when environment-variable discovery is inconvenient.
PhageLysData is constructed through sequential and inspectable stages.
Source-specific acquisition
↓
Source package auditing
↓
Sequence and metadata normalization
↓
Evidence/assertion construction
↓
Cross-source exact-sequence integration
↓
Evidence-aware resource universes
↓
Core evidence Tiers and canonical target classes
↓
Physicochemical characterization
↓
Frozen UniProtKB annotation enrichment
↓
Independent InterProScan enrichment
↓
Existing PDB / AlphaFold DB structural linkage
↓
PLM and one-hot numerical representations
↓
Construction closure and validation
↓
Resource characterization
↓
Portable public-release materialization
The principal integration and downstream construction stages are:
| Stage | Purpose |
|---|---|
| 26 | Build integrated exact-sequence resource |
| 27 | Define Core, Prediction Extension, Context, canonical target classes, and evidence Tiers |
| 28 | Compute Core physicochemical descriptors |
| 29 | Materialize frozen UniProtKB annotation enrichment |
| 30 | Prepare, run, and materialize independent InterProScan enrichment |
| 31 | Link and validate existing PDB / AlphaFold DB structural assets |
| 32 | Generate and finalize PLM / one-hot representation layer |
| 33 | Finalize resource construction |
| 34 | Characterize the frozen resource |
| 35 | Materialize organized workspace and portable public release |
Completed stages are treated as frozen unless an actual implementation or data-integrity error is identified.
The notebooks/ directory demonstrates how a user can work directly with the public PhageLysData release.
| Notebook | Purpose |
|---|---|
00_getting_started.ipynb |
Load the release, inspect Core metadata, filter entities, and retrieve associated assets |
01_resource_characterization.ipynb |
Reproduce descriptive resource characterization and release-facing summary outputs |
02_embedding_space_v0_2.ipynb |
Explore a released PLM representation using PCA and UMAP |
03_clustering_example_v0_2.ipynb |
Demonstrate unsupervised grouping of the released PLM space |
04_classification_example.ipynb |
Demonstrate simple multiclass supervised learning using released PLM embeddings |
05_candidate_selection_v0_2.ipynb |
Perform evidence-aware biological candidate retrieval and integrated annotation inspection |
The notebooks:
- consume only public release assets;
- use
sequence_entity_idas the stable join key; - do not access source-specific raw files or processing-stage outputs;
- write derived outputs outside the release directory;
- do not modify the distributed release;
- are intended to demonstrate interoperability and reuse, not state-of-the-art predictive performance.
The classification notebook uses a deliberately simple stratified random train/test split and should be interpreted as a reuse demonstration rather than a homology-controlled predictive benchmark.
The clustering notebook treats computational clusters as exploratory groups and does not equate them with biological families.
The candidate-selection notebook performs deterministic rule-based retrieval and does not claim validated candidate ranking or prioritization.
Publication-facing figure notebooks are maintained separately under:
si_figures/
They are intentionally separated from the analytical notebooks so that manuscript aesthetics can evolve without changing the frozen biological or analytical results.
| Notebook | Publication-facing output | Primary input |
|---|---|---|
S02_physicochemical_properties_by_class.ipynb |
Physicochemical distributions by Core class | Public Core release |
S03_annotation_asset_coverage.ipynb |
Annotation, structural, and numerical asset coverage | Public Core release |
S04_embedding_space_figure.ipynb |
PCA/UMAP latent-space figure | notebook_outputs/02_embedding_space/ |
S05_hdbscan_clustering_figure.ipynb |
HDBSCAN clustering figure | notebook_outputs/03_clustering_example/ |
S06_supervised_classification_figure.ipynb |
Four-class classification figure | notebook_outputs/04_classification_example/ |
S07_candidate_retrieval_figure.ipynb |
Evidence-aware depolymerase retrieval figure | notebook_outputs/05_candidate_selection/ |
The SI figure notebooks:
- do not redefine resource membership, canonical target class, or evidence Tier;
- do not rerun PCA, UMAP, HDBSCAN, classification, or candidate selection when frozen outputs are available;
- validate expected frozen counts and analysis contracts before plotting;
- export publication figures in vector PDF and SVG formats plus high-resolution PNG;
- export the plotting tables used for each figure;
- write generated outputs below
si_figures/generated/.
A typical generated structure is:
si_figures/
├── S0X_...ipynb
└── generated/
├── S02_physicochemical_properties/
├── S03_annotation_asset_coverage/
├── S04_embedding_space/
├── S05_hdbscan_clustering/
├── S06_supervised_classification/
└── S07_candidate_retrieval/
These files are manuscript derivatives and should not be confused with the authoritative Zenodo resource release.
Clone the repository and create the frozen environment:
git clone https://github.com/kren-ai-lab/phagelysdata.git
cd phagelysdata
conda env create -f environment.yml
conda activate phagelysdataDownload and unpack the PhageLysData v1.0 release from:
https://doi.org/10.5281/zenodo.22046027
Set the release path:
export PHAGELYSDATA_ROOT=/path/to/PhageLysData_v1.0If recreating publication figures from frozen example outputs:
export PHAGELYSDATA_NOTEBOOK_OUTPUTS=/path/to/phagelysdata/notebook_outputsStart Jupyter:
jupyter labThen open:
notebooks/00_getting_started.ipynb
A minimal Python example is:
from pathlib import Path
import pandas as pd
release_root = Path("/path/to/PhageLysData_v1.0")
core = pd.read_parquet(
release_root / "core" / "phagelysdata_core.parquet"
)
high_confidence_depolymerases = core.loc[
core["canonical_target_class"].eq("depolymerase")
& core["assigned_tier"].isin(["Tier 1", "Tier 2"])
]
print(high_confidence_depolymerases.shape)For a complete walkthrough of the public notebook suite, see notebooks/README.md.
PhageLysData is designed around explicit staged processing and frozen outputs.
Key reproducibility features include:
- exact-sequence entity identifiers derived from normalized sequence identity;
- preservation of source-level provenance;
- explicit prediction-derived evidence tracking;
- frozen Core / Prediction Extension / Context membership;
- frozen canonical target classes and evidence Tiers;
- independent UniProtKB-reported and InterProScan-derived annotation layers;
- explicit representation eligibility rules;
- reproducible numerical-representation settings;
- existing-structure asset manifests and coordinate-file checks;
- stage-level validation reports;
- release-level asset manifests;
- SHA-256 checksums for distributed assets;
- release-only filesystem sanitization to avoid developer-specific absolute paths;
- frozen worked-example outputs supporting publication-figure regeneration without analytical drift.
The public release includes:
MANIFEST.tsv
CHECKSUMS.sha256
These files allow users to inspect the distributed asset inventory and verify file integrity.
If you use PhageLysData, please cite the frozen v1.0 data release:
Medina-Ortiz, D., Olivera-Nappa, Á., Lienqueo, M. E., Ramírez, C., & Romero, J. (2026). PhageLysData: an evidence-aware and AI-ready dataset of phage lytic enzymes and depolymerases (Version 1.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.22046027
DOI: 10.5281/zenodo.22046027
Version: 1.0
Machine-readable citation metadata are provided in CITATION.cff.
The associated manuscript uses the same resource title and author list. Once a preprint or journal DOI is available, the publication citation can additionally be linked as the preferred citation without changing the archived PhageLysData v1.0 dataset DOI.
Code, workflows, executable notebooks, and environment specifications in this repository are distributed under the MIT License.
See LICENSE.
PhageLysData-original components, including the harmonization framework, controlled vocabulary, metadata schema, evidence-resolution rules, documentation, and derived records, are distributed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.
Third-party sequences, annotations, structural assets, and other source-derived content remain governed by the terms and licences of their original providers.
The authoritative licensing statement for the archived v1.0 data release is provided with the Zenodo record:
https://doi.org/10.5281/zenodo.22046027
For questions, issues, or reproducibility problems, please use the GitHub issue tracker:
https://github.com/kren-ai-lab/phagelysdata/issues
Repository:
https://github.com/kren-ai-lab/phagelysdata
Data release:
https://doi.org/10.5281/zenodo.22046027
PhageLysData is maintained within the Kren-AI Lab research ecosystem.