FAIR Metadata

Overview

This repository provides FAIR-compliant metadata for the ELIXIR 3D-BioInfo Benchmark for Protein–Protein Interfaces – a dataset comprising 1,677 protein structure interfaces with 844 physiological and 833 non-physiological homodimer interfaces for machine learning and structural bioinformatics applications.

The ppi_benchmark_fair.py script generates machine-readable JSON-LD metadata compliant with multiple standards:

Quick Start

# Clone repository
git lfs clone https://github.com/biofold/ppi-benchmark-fair.git
cd ppi-benchmark-fair

# Install requirements
pip install -r requirements.txt

# Generate basic metadata
python ppi_benchmark_fair.py --output bioschema

# Generate enriched metadata (recommended)
python scripts/ppi_benchmark_fair.py \
  --fetch-pdb-metadata \
  --check-pdb-label \
  --cluster data/ppi_benchmark_seqs.clust_25_05 \
  --output bioschema \
  --verbose

Dataset Statistics

FAIR Compliance Evaluation

This repository has been evaluated using comprehensive FAIR principles analysis. Overall Score: 87.5/100

Metadata Architecture

Generated File Structure

bioschema/
├── dataset_with_interfaces.json          # Complete dataset (all 1,677 interfaces)
├── interface_protein_pairs/              # Individual interface files
│   ├── interface_1A17_6.json            # ProtCID format
│   ├── interface_1A3A_1.json    # QSalign format
│   └── ... (1,677 files total)
├── fair_metadata_package.json            # FAIR Architecture package
├── embedded_markup.html                  # HTML with JSON-LD for web discovery
├── manifest.json                         # File inventory and checksums
└── pdb_metadata_cache.json              # Optional: Cached PDB metadata

Data Schema

{
  "@context": ["https://schema.org/", {"cr": "https://mlcommons.org/croissant/1.0"}],
  "@type": ["Dataset", "cr:Dataset"],
  "dct:conformsTo": "https://bioschemas.org/profiles/Dataset/1.0-RELEASE",
  "hasPart": [ /* 1,677 interface items */ ],
  "distribution": [
    {
      "@type": "DataDownload",
      "encodingFormat": "text/csv",
      "contentUrl": "https://.../benchmark_annotated_updated_30042023.csv"
    }
  ]
}

Interface ID Formats

• ProtCID: {PDB_ID}_{integer} (e.g., 1ABC_1)
• QSalign: {PDB_ID}_{integer} (e.g., 1DEF_assembly1)
• Cleaned: Original InterfaceID with standardized formatting

Usage Examples

Basic Python Usage

import json
import pandas as pd
from pathlib import Path

# Load dataset metadata
with open('bioschema/dataset_with_interfaces.json', 'r') as f:
    dataset = json.load(f)

print(f"Dataset: {dataset['name']}")
print(f"Total interfaces: {dataset['numberOfItems']}")  # 1677
print(f"License: {dataset['license']}")

# Load specific interface
interface_file = 'bioschema/interface_protein_pairs/interface_1A17_5.json'
with open(interface_file, 'r') as f:
    interface = json.load(f)

# Extract features for ML
features = {}
for prop in interface['additionalProperty']:
    if prop['name'] == 'physio':
        features['label'] = 1 if prop['value'] else 0
    elif prop['name'] == 'Buried Surface Area (BSA)':
        features['bsa'] = prop['value']
    elif prop['name'] == 'ClusterID':
        features['cluster'] = prop['value']  # For stratified splits

print(f"Features: {features}")

Command Line Options

# Full metadata generation with all enrichments
python ppi_benchmark_fair.py \
  --csv-url "https://raw.githubusercontent.com/.../benchmark.csv" \
  --mmcif-url "https://raw.githubusercontent.com/.../mmcif/" \
  --pdb-url "https://raw.githubusercontent.com/.../pdb/" \
  --fetch-pdb-metadata \           # Fetch PDB metadata from RCSB API
  --check-pdb-label \              # Validate chains in PDB files
  --check-cif-label \              # Validate chains in mmCIF files
  --cluster "data/clusters.txt" \  # Add sequence cluster information
  --output "metadata_output" \     # Custom output directory
  --verbose \                      # Detailed logging
  --separator ","                  # CSV separator (auto-detects if fails)

Sequence Clustering Information

Interfaces are clustered using BLASTClust with 90% sequence identity threshold:

# Command used for clustering
blastclust -i sequences.fasta -o clusters.txt -S 25 -L 0.5 -b F

# Interpretation:
# -S 25: Score threshold 25 bits
# -L 0.5: Length coverage threshold 50%
# -b F: Coverage on both neighbours False

# Result: ~1050 clusters across 1,677 interfaces

Cluster Properties in Metadata:

• ClusterID: First InterfaceID in each BLASTClust line
• ClusterSize: Number of interfaces in the cluster
• ClusterMembers: List of other interfaces in same cluster
• ClusterMethod: "BLASTClust sequence clustering"
• ClusterMethodOptions: "-S 25 -L 0.5 -b F"

For Different User Communities

Machine Learning Researchers

• Stratified Splits: Cluster-based partitioning for non-redundant training/validation
• Feature-Rich: 50+ structural and sequence features per interface
• ML-Ready: Croissant 1.0 compatible for automatic pipeline integration
• Reproducible: Versioned features with full provenance

Structural Biologists

• Structurally Validated: Chain IDs verified against biological assemblies
• Biologically Annotated: GO terms, organism information, experimental details
• FAIR Compliant: Persistent identifiers, provenance tracking
• Multi-Format: PDB and mmCIF representations available

Data Stewards & Curators

• Schema-Compliant: Bioschemas and Schema.org adherence
• Provenance-Aware: Clear lineage from raw data to enriched metadata
• Extensible: additionalProperty for custom annotations
• Web-Discoverable: JSON-LD embedded in HTML for search engines

Bioinformaticians

• API-Ready: Structured JSON for programmatic access
• Standards-Based: EDAM, GO, UniProt cross-references
• Pipeline-Friendly: Modular, incremental metadata generation
• Version-Controlled: Git-tracked with clear update history

Technical Implementation

Design Principles

1. Modular Enrichment: Optional steps (PDB metadata, assembly validation, clustering)
2. Provenance Preservation: All modifications timestamped and logged
3. Schema Safety: Extensions use additionalProperty without breaking validation
4. FAIR-by-Design: Built with Findable, Accessible, Interoperable, Reusable principles

Processing Pipeline

CSV Data → Parse → ProteinInterface Objects → Optional Enrichment:
  ├── Assembly Chain Validation (--check-pdb-label/--check-cif-label)
  ├── PDB Metadata Fetching (--fetch-pdb-metadata)
  └── Cluster Assignment (--cluster file)
    ↓
Generate Metadata → Validate → Output Files

FAIR Improvements Roadmap

Based on the FAIR assessment (87.5/100), here are planned improvements:

Low Priority (Potential +5 points)

• Create .github/ISSUE_TEMPLATE/ for structured issue reporting

Medium Priority (Potential +20 points)

• Specify access rights in metadata (open/restricted/closed)
• Include format information (MIME types, extensions) in metadata

Low Priority (Potential +15 points)

• Add repository topics on GitHub settings
• Create GitHub releases with version tags
• Enable and populate documentation wiki

Target FAIR Score: 100/100 (Currently: 87.5)

License and Attribution

License

Creative Commons Attribution 4.0 International (CC BY-NC 4.0)
This work is licensed under a Creative Commons Attribution 4.0 International License.

Citation

@article{schweke2023discriminating,
   title={Discriminating physiological from non-physiological interfaces in structures of protein complexes: A community-wide study},
   author={Schweke, H. and Xu, Q. and Cazals, F. and Teyra, J. and Zimmermann, O. and Brenke, R. and Mihalek, I. and Res, I. and Ferré, A. and Lafita, A. and Guzzo, C. R. and Bordogna, A. and Bonvin, A. M. J. J. and Dey, S. and Gao, M. and Vangone, A. and Oliva, R. and Guarnera, E. and Roche, D. B. and Bhattacharya, S. and Brylinski, M. and Dijkstra, M. and Esquivel-Rodríguez, J. and Kihara, D. and Lensink, M. F. and Murakami, Y. and Nadzirin, N. and Nagarajan, R. and Oliveira, S. H. P. and Pires, D. E. V. and Roy, R. S. and Sanchez-Garcia, R. and Schueler-Furman, O. and Trellet, M. and Wodak, S. J.},
   journal={Proteomics},
   volume={23},
   number={17},
   pages={e2200323},
   year={2023},
   publisher={Wiley},
   doi={10.1002/pmic.202200323}
}

@dataset{elixir2024fairmetadata,
   title={ELIXIR 3D-BioInfo Benchmark for Protein-Protein Interfaces FAIR Metadata},
   author={{ELIXIR 3D-BioInfo Community}},
   year={2024},
   version={1.0},
   publisher={ELIXIR},
   doi={10.5281/zenodo.XXXXXXX}
}

Dataset Reference Publication

"Discriminating physiological from non-physiological interfaces in structures of protein complexes: A community-wide study"
📄 https://doi.org/10.1002/pmic.202200323

Contact

• ELIXIR 3D-BioInfo Community: https://elixir-europe.org/platforms/3d-bioinfo
• Repository Issues: GitHub Issues
• Dataset Source: Original Benchmark

Related Resources

Contributing

We welcome contributions to improve FAIR compliance! See our GitHub Issues for current improvement tasks.

Support

For questions or support, please:

1. Check the FAIR Improvements Roadmap section
2. Review existing GitHub Issues
3. Create a new issue with detailed description

This project is part of the ELIXIR 3D-BioInfo Community's efforts to promote FAIR data practices in structural bioinformatics.