molstar / molstar

A comprehensive macromolecular library

Mol*

The goal of Mol* (/'mol-star/) is to provide a technology stack that serves as a basis for the next-generation data delivery and analysis tools for (not only) macromolecular structure data. Mol* development was jointly initiated by PDBe and RCSB PDB to combine and build on the strengths of LiteMol (developed by PDBe) and NGL (developed by RCSB PDB) viewers.

When using Mol*, please cite:

David Sehnal, Sebastian Bittrich, Mandar Deshpande, Radka Svobodová, Karel Berka, Václav Bazgier, Sameer Velankar, Stephen K Burley, Jaroslav Koča, Alexander S Rose: Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures, Nucleic Acids Research, 2021; https://doi.org/10.1093/nar/gkab314.

Protein Data Bank Integrations

• The pdbe-molstar library is the Mol* implementation used by EMBL-EBI data resources such as PDBe, PDBe-KB and AlphaFold DB. This implementation can be used as a JS plugin and a Web component and supports property/attribute-based easy customisation. It provides helper methods to facilitate programmatic interactions between the web application and the 3D viewer. It also provides a superposition view for overlaying all the observed ligand molecules on representative protein conformations.

• rcsb-molstar is the Mol* plugin used by RCSB PDB. The project provides additional presets for the visualization of structure alignments and structure motifs such as ligand binding sites. Furthermore, rcsb-molstar allows to interactively add or hide of (parts of) chains, as seen in the 3D Protein Feature View.

Project Structure Overview

The core of Mol* consists of these modules (see under src/):

• mol-task Computation abstraction with progress tracking and cancellation support.
• mol-data Collections (integer-based sets, interface to columns/tables, etc.)
• mol-math Math related (loosely) algorithms and data structures.
• mol-io Parsing library. Each format is parsed into an interface that corresponds to the data stored by it. Support for common coordinate, experimental/map, and annotation data formats.
• mol-model Data structures and algorithms (such as querying) for representing molecular data (including coordinate, experimental/map, and annotation data).
• mol-model-formats Data format parsers for mol-model.
• mol-model-props Common "custom properties".
• mol-script A scripting language for creating representations/scenes and querying (includes the MolQL query language).
• mol-geo Creating (molecular) geometries.
• mol-theme Theming for structure, volume and shape representations.
• mol-repr Molecular representations for structures, volumes and shapes.
• mol-gl A wrapper around WebGL.
• mol-canvas3d A low-level 3d view component. Uses mol-geo to generate geometries.
• mol-state State representation tree with state saving and automatic updates.
• mol-plugin Allow to define modular Mol* plugin instances utilizing mol-state and mol-canvas3d.
• mol-plugin-state State transformations, builders, and managers.
• mol-plugin-ui React-based user interface for the Mol* plugin. Some components of the UI are usable outside the main plugin and can be integrated into 3rd party solutions.
• mol-util Useful things that do not fit elsewhere.

Moreover, the project contains the implementation of servers, including

• servers/model A tool for accessing coordinate and annotation data of molecular structures.
• servers/volume A tool for accessing volumetric experimental data related to molecular structures.
• servers/plugin-state A basic server to store Mol* Plugin states.

The project also contains performance tests (perf-tests), examples, and cli apps (CIF to BinaryCIF converter and JSON domain annotation to CIF converter).

Previous Work

This project builds on experience from previous solutions:

• LiteMol Suite
• WebChemistry
• NGL Viewer
• MMTF
• MolQL
• PDB Component Library
• And many others (list will be continuously expanded).

Building & Running

Build:

npm install
npm run build

Build automatically on file save:

npm run watch

If working on just the viewer, npm run watch-viewer will provide shorter compile times.

Build with debug mode enabled:

DEBUG=molstar npm run watch

Debug/production mode in browsers can be turned on/off during runtime by calling setMolStarDebugMode(true/false, true/false) from the dev console.

Cleaning and forcing a full rebuild

npm run clean

Wipes the build and lib directories and .tsbuildinfo files.

npm run rebuild

Runs the cleanup script prior to building the project, forcing a full rebuild of the project.

Use these commands to resolve occassional build failures which may arise after some dependency updates. Once done, npm run build should work again. Note that full rebuilds take more time to complete.

Build for production:

NODE_ENV=production npm run build

Run

If not installed previously:

npm install -g http-server

...or a similar solution.

From the root of the project:

http-server -p PORT-NUMBER

and navigate to build/viewer

Code generation

CIF schemas

node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/mmcif.ts -p mmCIF
node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/ccd.ts -p CCD
node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/bird.ts -p BIRD
node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/cif-core.ts -p CifCore -aa

Lipid names

node lib/commonjs/cli/lipid-params -o src/mol-model/structure/model/types/lipids.ts

Ion names

node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-ions.js src/mol-model/structure/model/types/ions.ts

Saccharide names

node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-saccharides.js src/mol-model/structure/model/types/saccharides.ts

Other scripts

Create chem comp bond table

node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-table.js build/data/ccb.bcif -b

Test model server

export NODE_PATH="lib"; node build/src/servers/model/test.js

State Transformer Docs

export NODE_PATH="lib"; node build/state-docs

Convert any CIF to BinaryCIF (or vice versa)

node lib/commonjs/servers/model/preprocess -i file.cif -ob file.bcif

To see all available commands, use node lib/commonjs/servers/model/preprocess -h.

Or

node lib/commonjs/cli/cif2bcif

E.g.

node lib/commonjs/cli/cif2bcif src.cif out.bcif.gz
node lib/commonjs/cli/cif2bcif src.bcif.gz out.cif

Development

Installation

If node complains about a missing acorn peer dependency, run the following commands

npm update acorn --depth 20
npm dedupe

Editor

To get syntax highlighting for shader files add the following to Visual Code's settings files and make sure relevant extensions are installed in the editor.

"files.associations": {
    "*.glsl.ts": "glsl",
    "*.frag.ts": "glsl",
    "*.vert.ts": "glsl"
},

Publish

Prerelease

npm version prerelease # assumes the current version ends with '-dev.X'
npm publish --tag next

Release

npm version 0.X.0 # provide valid semver string
npm publish

Deploy

npm run test
npm run build
node ./scripts/deploy.js # currently updates the viewer on molstar.org/viewer

Contributing

Just open an issue or make a pull request. All contributions are welcome.

Funding

Funding sources include but are not limited to:

• RCSB PDB funding by a grant [DBI-1338415; PI: SK Burley] from the NSF, the NIH, and the US DoE
• PDBe, EMBL-EBI
• CEITEC
• EntosAI

molstar's Issues

Improve supercell and crystal contacts for some (odd) spacegroup definitions

for example 2D3E

Add proxy spheres for non-elemental loci in measurements

When doing, e.g., distance measurements between, e.g., residues it would be nice to draw two little proxy spheres at the end of the dashes distance measurement line. Hovering over the proxy spheres should show label.

Add proxy spheres where the pink circles are.

Add dynamic scale bar to Canvas3D

Add dynamic (will adjust on zooming) scale bar like on online map tools to the Canvas3D.

Remove structure from Viewer

I managed to generate all the features that I want but I found no function to remove loaded structures from the viewer. In the old NGL there was a removeAllComponents function but I cannot find one for molstar. Could you help ?

em density map is displaied as a sphere...

Hi! Nice project. I've found this

This is not how users expect to visualise em maps.

This is how NGL does it and chimera does something similar:

Also, I didn't find a way to play with the sigma value.

Roadmap question regarding 3D editing functionality

Hello,

is this in scope for this project?

Regards,
Jacob

Residue rainbow coloring pdb format

Residue rainbow coloring does not behave as expected when N-terminal residue numbering starts at large indexes in pdb format files. In the attached file the full ribbon is displayed in red

101M.pdb.zip

Hyperball representation

Similar to that in NGL (a demo is in http://nglviewer.org/ngl/gallery/).

Support for aromatic rings

• use aromatic flag for each bond
• extract from chemComp when available
• calculate based on ring planarity for rings >3
• [X]add isAromatic ring property/grouping when all ring bonds have aromatic flag or (ring is planar and only includes the following elements: B, C, N, O, SI, P, S, GE, AS, SN, SB, BI)
• add torus shape
• use torus (or alternatively dashed bonds inside the ring) for aromatic rings, i.e. draw instead of double bonds (needs new visual as part of ball&stick and lines representation)

Input SDF/MOL and XYZ files

SDF/MOL and XYZ are formats I use for small molecules. I did not yet see these in the source code so I created this issue to track it.

Fix chain-id coloring for structures from pdb-dev

Fix chain-id coloring for structures from pdb-dev. Curently they are all white. Might be an issue with Model.AsymIdOffset.

Script to extract SNFG to component name mapping from CCD

Should extend the existing cli/chem-comp-bonds/ script (renamed to chem-comp). Data should go to src\mol-model\structure\model\types\carbohydrates.ts. Include all chemical components with the string 'SACCHARIDE' included in their type (_chem_comp.type). Extract _pdbx_chem_comp_identifier.identifier Will replace CommonSaccharideNames in src\mol-model\structure\structure\carbohydrates\constants.ts.

Related: #62

Vault protein assembly not rendered completely

I am evaluating the Mol* viewer on the RCSB beta page, so I am not sure if issues there have been resolved here already. But I found that 4V60 is not fully shown (only the top and bottom part are shown as surface).

Fix building of /src/cli tools, need full lib as es5

Fix building of /src/cli tools, need full lib as es5. Currently only cli tools that don't use any mol* modules work.

Chances for Three.js interop/wrapper?

What a great project!

Since this is a lot more low-level than NGL, how are the chances that there will be an official interface to Three.js at some point? It would make sense to include molecule geometry into existing tools, given the huge ecosystem. E.g. implementing advanced controls for XR with raycasting, colliders etc. will be hard (and unnecessary) to do from scratch for this project.

Mol* seems to move fast paced at the moment, so maintaining a wrapper may currently be a liability. Could you give a an estimate when in the future will be a good point that such a thing may be implemented?

(I am coming over from a related issue with NGL)

Consider adding a sequence loci

Would make it easier to communicate with external code that only needs residue/sequences info. Would simplify sequence widget code.

Calculate secondary structure for coarse models

A straightforward option is the algorithm published by Zhang and Skolnick in their TM-align paper.
TM-align: a protein structure alignment algorithm based on the Tm-score (2005) NAR, 33(7) 2302-2309. An implementation of it can be found in NGL (https://github.com/arose/ngl/blob/master/src/structure/structure-utils.ts).

The code should be added along the dssp implementation (https://github.com/molstar/molstar/tree/master/src/mol-model-props/computed/secondary-structure).

Model/density server external configuration

It would be nice to be able to configure the DefaultModelServerConfig object using either environment variables or externalized config file. I'd want to add this into a Dockerfile for Kubernetes deployment. Currently, I can have a copy of the config with the settings I want and pass that on to the docker container before build. But this assumes the TS file doesn't change in the near future. but an externalized JSON/YAML config is easy enough to replace without breaking things unnecessarily.

Account for charge in the type_symbol field of cif-core files

Account for charge in the type_symbol field of cif-core files, e.g.,

loop_
_atom_site_label
_atom_site_type_symbol
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
_atom_site_occupancy
_atom_site_U_iso_or_equiv
C1 C+2 0.0829 0.3055 0.4122 1 0.0
O2 O-2 0.2097 0.1578 0.1427 1 0.0
C3 C+2 0 -0.094 0.25 1 0.0
O3 O-2 0 -0.256 0.25 1 0.0
C2 C+2 0.1299 0.1572 0.183 1 0.0
O1 O-2 0.1364 0.3922 0.5165 1 0.0
Fe1 Fe 0 0.1656 0.25 1 0.0

Presets: Show no cartoon for structures with many polymer-gaps

For files that only contain a very partial, fragmented model, e.g. a binding site, it does make not much sense to show a cartoon representation.

Find presets code at https://github.com/molstar/molstar/blob/master/src/mol-plugin-state/builder/structure/representation-preset.ts.

Use multi-sample render-targets for MSAA in webgl2

For multi-sample anti-aliasing use MS render buffer in webgl2.

Gaps in protein caused by deformations

After applying some deformation using Normal Mode Analysis to a protein, geometry is not canonical anymore and when trying to visualize the molecule with Pymol or Chimera, lines and ribbons usually contain dashed lines for representing that effect. Is there any way to have such effect in Mol*? I see the same behavior coming from NGLViewer.
Thanks a lot for your help and time!

Ligands are not Displayed in Symmetry Mates

When the Structure Type Symmetry Mates option is selected, the ligands are not displayed for the model chain copies.

Load local files

Hi Sorry to bother you, I was wondering if it is possible to load locally generated pdb models.

Interval quantization encoder should use max as upper bound

The interval quantization encoder uses numSteps as upper bound.

https://github.com/molstar/molstar-proto/blob/50ebd5467cbf80da6898bf307a8062f9cd300b6d/src/mol-io/common/binary-cif/array-encoder.ts#L175

The line should probably read
else if (v >= max) output[i] = max;
otherwise the example at https://github.com/dsehnal/BinaryCIF#interval-quantization cannot be recreated.

Cellpack extension: Measurements are broken and return 0

Example, load influenza envelope and select two residues for distance measurement. This will always return zero.

Can the viewer be used as a standalone package?

Can anyone share how to use the mol-viewer as a standalone package? like can be imported to React.

Thank you in advance!

Improve outlines

• take object id into account
• take zoom level into account

Jupyter widget

Is there is any plan to make a Jupyter plugin out of this library?

Similar to https://github.com/arose/nglview

Show nucleotide rings/blocks for multiple locations

Show nucleotide rings/blocks for multiple locations (including from microheterogeneity).

One option is to get all alt ids occurring for a residueIndex and then loop over them and use the alt id when calling index.findAtomOnResidue in https://github.com/molstar/molstar/blob/master/src/mol-repr/structure/visual/nucleotide-block-mesh.ts and https://github.com/molstar/molstar/blob/master/src/mol-repr/structure/visual/nucleotide-ring-mesh.ts.

How to upgrade to Mol* from NGLViewer?

Hi Alex, as someone who currently has NGL Viewer integrated into their own work, is there a guide or best practice on how to replace it with Mol*? I'd need to retain both the view and the ability to interrogate the underlying model data (atoms, residues, distances etc).

Improve AO

Improve ambient occlusion to take model scale and zoom level into account.

Support color themes that depend on other object of the state tree

Would allow to color volumes by other volumes, color structures by volumes, color volumes by structures.

First step has been done with AssignColorVolume in https://github.com/molstar/molstar/blob/master/src/mol-plugin-state/transforms/volume.ts

Ball & Stick representation: option to show half-bonds of parent structure.

Add an option to the Ball & Stick representation for showing half of a bond where one atom is in the current structure but the other only in the parent structure.

This would allow to create multiple components with Ball & Stick representation and still show bonds between them.

Investigate: JSON representation of CIF information (DRAFT)

see http://comcifs.github.io/cif-json.html

Bond order

Hello
The bonds order is not displayed correctly in non-polymers representations. It only shows correctly if it appears in the mmcif file (at least in pdb format it doesn't show correctly)

Installing from readme

Everything is running on Ubuntu 18.04 LTS
VS Code
node -v: v13.10.1
npm -v: 6.14.5
tsc -v: Version 3.9.3

If you clone/download and follow the instructions it will fail at npm run build with the following errors:

[0] tsc --incremental exited with code 0
[1] src/perf-tests/structure.ts(322,41): error TS2339: Property 'auth_comp_id' does not exist on type '{ key: Property<ResidueIndex>; group_PDB: Property<"ATOM" | "HETATM">; label_seq_id: Property<number>; auth_seq_id: Property<number>; ... 6 more ...; chem_comp_type: Property<...>; }'.
[1] src/perf-tests/structure.ts(434,41): error TS2339: Property 'auth_comp_id' does not exist on type '{ key: Property<ResidueIndex>; group_PDB: Property<"ATOM" | "HETATM">; label_seq_id: Property<number>; auth_seq_id: Property<number>; ... 6 more ...; chem_comp_type: Property<...>; }'.
[1] src/perf-tests/structure.ts(438,76): error TS2339: Property 'auth_comp_id' does not exist on type '{ key: Property<ResidueIndex>; group_PDB: Property<"ATOM" | "HETATM">; label_seq_id: Property<number>; auth_seq_id: Property<number>; ... 6 more ...; chem_comp_type: Property<...>; }'.
[1] src/perf-tests/structure.ts(445,51): error TS2339: Property 'auth_comp_id' does not exist on type '{ key: Property<ResidueIndex>; group_PDB: Property<"ATOM" | "HETATM">; label_seq_id: Property<number>; auth_seq_id: Property<number>; ... 6 more ...; chem_comp_type: Property<...>; }'.
[1] src/servers/model/query/atoms.ts(66,34): error TS2339: Property 'label_comp_id' does not exist on type '{ key: Property<ResidueIndex>; group_PDB: Property<"ATOM" | "HETATM">; label_seq_id: Property<number>; auth_seq_id: Property<number>; ... 6 more ...; chem_comp_type: Property<...>; }'.
[1] src/servers/model/query/atoms.ts(71,34): error TS2339: Property 'auth_comp_id' does not exist on type '{ key: Property<ResidueIndex>; group_PDB: Property<"ATOM" | "HETATM">; label_seq_id: Property<number>; auth_seq_id: Property<number>; ... 6 more ...; chem_comp_type: Property<...>; }'.
[1] tsc --build tsconfig.commonjs.json --incremental exited with code 1
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build-tsc: `concurrently "tsc --incremental" "tsc --build tsconfig.commonjs.json --incremental"`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] build-tsc script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

The way I fixed it: navitate to those files ex: scr/perf-tests/structure.ts and comment out everything that has 'auth_comp_id'

It should work after that. I do not know if this is optimal or not but it works.

'undefined' in sequence tab

The sequence tab will report undefined for HETATMs. See example for 1brr, first label_comp_id is PCA.

Iirc, it worked previously. Now

molstar/src/mol-plugin-ui/sequence/polymer.ts

Line 30 in f6acf0a

return this.sequence.label.value(seqIdx);

will return the string 'undefined'. Might be some other underlying issue, otherwise I can also prepare a simple PR.

Improper matrix rotation which inverts mesh inside/outside

Example CCDC 1422222 has improper rotation which inverts mesh inside/outside (add transparent surface to see)

In the image below, the transparent surfaces on the right should be green as well. They are grey because the inside of surfaces is shown in grey by default.

Session: mol-star_state_2020-5-22-18-45-10.zip

Update representation type / opacity using API

Hi,

I am loading my PDB file using the following, which works very nicely:

var viewer = new molstar.Viewer('app', options)
viewer.loadStructureFromUrl("url_to_pdb_file", format='pdb')

I would like to do the following:

• change the 3D representation type from Cartoon to Molecular Surface.
• change the opacity from 1 to 0.5.

This can be done easily using the left side panel - however, I would like to do this using an API if possible.

Looking at the code, I see that loadStructureFromUrl() function returns a promise but I can't seem to access any objects. e.g.

viewer.loadStructureFromUrl("url_to_pdb_file", format='pdb').then(function(obj) {
    console.log('Finished Loading');
    console.log(obj);
});

I would appreciate any help with regards to this.

Many Thanks,
Ismail

Server documentation: Replace Swagger with ReDoc

ReDoc npm package: https://www.npmjs.com/package/redoc

Requires changes to https://github.com/molstar/molstar/tree/master/src/servers/common as a starting point.

CIF-core of diamond lacks bonds

https://www.crystallography.net/cod/9008564.html
Right-click for the Jmol popup menu and pick Symmetry > Reload {1, 1, 1}

Here is a screenshot from JSmol and Mol* with the assembly to 'symmetry mates' in Mol*.

I don't know how to get the single filled in unit-cell in Mol* as in JSmol. I'm also curious if it is possible in Mol* to create a specific number of repeated unit-cells (e.g. 10x10x1).

Documentation?

Hi there,

Is there any documentation on how to use this code to load/visualize/manipulate structures? Even any sort of API documentation would be great!

Thanks

Building graphql schema fails

I've followed the procedure from the README, but it failed for me at the graphql building level with the following message

node data/rcsb-graphql/codegen.js
  ✔ Parse configuration
  ❯ Generate outputs
    ❯ Generate /mypath/molstar/src/mol-model-props/rcsb/graphql/types.ts
      ✖ Load GraphQL schemas
        → getaddrinfo ENOTFOUND rest-staging.rcsb.org rest-staging.rcsb.org:80
        Load GraphQL documents
        Generate


  Found 1 error

   ✖ /mypath/molstar/src/mol-model-props/rcsb/graphql/types.ts
    Error: getaddrinfo ENOTFOUND rest-staging.rcsb.org rest-staging.rcsb.org:80

Fix middle drag scrolls page in Firefox on win

See https://stackoverflow.com/questions/1930875/disabling-middle-click-scrolling-with-javascript for context info

Probably reuires change to https://github.com/molstar/molstar/blob/master/src/mol-util/input/input-observer.ts.

Load files remotely

Hi,

First of all, I would like to thank you for making this great software.

Now that we are in pandemic times, I was looking for a solution to visualize protein files that are in a remote machine to which I can connect through ssh. I was able to install Molstar on that machine and open an instance of the visualizer at home using ssh port forwarding. My question is: is there a way to load files present on the remote machine into this home instance?

I was trying something like what was described here for Jupyter Notebook/NGLView.

Thanks

TypeError: "group is undefined" upon loading from OPM

Hi,
while trying to load a structure from the OPM databased the following error appeared:
TypeError: "group is undefined"
parseRemark350 http://localhost/build/viewer/index.js:48603
pdbToMmCif http://localhost/build/viewer/index.js:49395
step http://localhost/build/viewer/index.js:183209
verb http://localhost/build/viewer/index.js:183190
__awaiter http://localhost/build/viewer/index.js:183183
__awaiter http://localhost/build/viewer/index.js:183179
pdbToMmCif http://localhost/build/viewer/index.js:49266
trajectoryFromPDB http://localhost/build/viewer/index.js:48367
step http://localhost/build/viewer/index.js:183209
verb http://localhost/build/viewer/index.js:183190
fulfilled http://localhost/build/viewer/index.js:183180
index.js:109125:33
updateSubtree http://localhost/build/viewer/index.js:109125
step http://localhost/build/viewer/index.js:183209
verb http://localhost/build/viewer/index.js:183190
rejected http://localhost/build/viewer/index.js:183181
here is one example of such file:
https://opm.phar.umich.edu/proteins/109
or direct link
https://opm-assets.storage.googleapis.com/pdb/1aa7.pdb
loading from disk give the same error.
Thanks in advance for looking into it.

Issue with UI set intersection and multiple chain instances

Example: https://molstar.org/viewer/?pdb=6lu7&pdb-provider=rcsb

In selection mode at chain picking level, select ASM_2 chain instance. Intersect with e.g. Helix. This should result in Helix of ASM_2 beeing selected. Actual result is that nothing is selected. Doing the same for ASM_1 gives the expected result.

Add per-group (screendoor) transparency to UI

Same way per-group coloring is done using the TransparencyStructureRepresentation3DFromBundle transform.

Script to extract ion names from CCD

Should extend the existing cli/chem-comp-bonds/ script (renamed to chem-comp). Data should go to src\mol-model\structure\model\types\ions.ts. Include all chemical components with the word "ion" in their name. Will replace IonNames in src\mol-model\structure\model\types.ts.

Related: #63