[question] Replacing API's file with local ones

[agdiaz]

Dear PDB-Topology-Viewer developers and maintainers,
First, thank you for building this visualization tool, it's great!

Rationale

I would like to contribute to extending it to support PDB files from other sources such as AlphaFold models or local PDBs that aren't published on PDBe.

I found that the function async getApiData(pdbId: string, chainId: string) has the responsibility to fetch the source files:

        const dataUrls = [
            `https://www.ebi.ac.uk/pdbe/api/pdb/entry/entities/${pdbId}`,
            `https://www.ebi.ac.uk/pdbe/api/mappings/${pdbId}`,
            `https://www.ebi.ac.uk/pdbe/api/topology/entry/${pdbId}`,
            `https://www.ebi.ac.uk/pdbe/api/validation/residuewise_outlier_summary/entry/${pdbId}`,
            `https://www.ebi.ac.uk/pdbe/api/pdb/entry/polymer_coverage/${pdbId}/chain/${chainId}`
        ]

I wonder if you could provide me with the information to know how to generate these files for a custom PDB. It means, which software should I run to generate the required information so that I may write an upper function that uses local files if they are provided or fetches the EBI's API if not.

Context and proposal

Below I describe the origin and format of each required file. Originally, they come from the EBI services through API requests, but the idea is to generate them locally in a way like:

<pdb-topology-viewer 
    pdb-id="file:///path/to/file.pdb" 
    entity-id="1" 
    mappings="file:///path/to/mappings.json"
    topology="file:///path/to/topology.json"
    residuewise-outlier-summary= "file:///path/to/residuewise_outlier_summary.json"
    polymer-coverage="file:///path/to/polymer_coverage.json"
></pdb-topology-viewer>

Or like a JS script:

<script>
   //Instantiate plugin after DOM content is loaded
   document.addEventListener('DOMContentLoaded', () => {

        //Create plugin instance
        var viewerInstance = new PdbTopologyViewerPlugin();

        //Set options (** All the available options are listed below in the documentation)
        var options = {
	   pdbId: "file:///path/to/file.pdb",
           entityId: "1",
           mappings: "file:///path/to/mappings.json",
           topology: "file:///path/to/topology.json",
           residuewiseOutlierSummary: "file:///path/to/residuewise_outlier_summary.json",
           polymerCoverage="file:///path/to/polymer_coverage.json"
        }
    
        //Get element from HTML/Template to place the viewer 
        var viewerContainer = document.getElementById('myViewer');

        //Call render method to display the 2D view
        viewerInstance.render(viewerContainer, options);
   });
</script>

File formats

PDB file

This file is requested via https://www.ebi.ac.uk/pdbe/api/pdb/entry/entities/${pdbId}.

It is a PDB file related to the target PDB ID.

Mappings file

This file is requested via https://www.ebi.ac.uk/pdbe/api/mappings/${pdbId}.

It is a JSON file that describes associated entries to the target PDB ID including "UniProt," "GO" (Gene Ontology), "InterPro," "Pfam," "EC" (Enzyme Commission), "CATH," "CATH-B," "SCOP," "HMMER," and "Ensembl."

Topology file

This file is requested via https://www.ebi.ac.uk/pdbe/api/topology/entry/${pdbId}.

It is a JSON file describing the secondary structure elements including the locations and paths of various structural elements such as strands, coils, termini, and helices, as well as the overall extent of the structural element within the protein entity.

Outlier summary file

This file is requested via https://www.ebi.ac.uk/pdbe/api/validation/residuewise_outlier_summary/entry/${pdbId}.

This JSON file provides information about the structural properties and potential outliers (such as clashes, bond angles, and RSRZ values) of specific residues within the protein's chain and model.

Polymer coverage file

This file is requested via https://www.ebi.ac.uk/pdbe/api/pdb/entry/polymer_coverage/${pdbId}/chain/${chainId}.

This JSON file provides information about the observed residues within a specific chain of the protein structure, including their starting and ending positions, residue numbers, author residue numbers, insertion codes, and structural asymmetry identifiers.

New "per-residue" values file

It would be great to have an extra file for more attributes related to each residue of the sequence such as the pLDDT for AF2 models. Having this file loaded may allow the widget to display more options in the dropdown to colour the shapes.

{
  "PDB ID": {
    "molecules": [
      {
        "entity_id": 1,
        "chains": [
          {
            "struct_asym_id": "A",
            "chain_id": "A",
            "residues": [
              {
                "residue": "M",
                "position": 1,
                "values": [
                  {
                    "name": "pLDDT",
                    "value": 0.91
                  },
                  {
                    "name": "hydrophilicity",
                    "value": 0.5
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Wrapping up

The idea is to provide the component a way to directly load the source file instead of fetching them from the EBI's API endpoints. To do so, I would like to know how to locally generate those files, and which software tools or online services I need to execute to get them.

Thank you in advance for your collaboration.

Kind regards from Brussels,
Adrián