Advanced scripting

Here we collected useful functions, scripting example codes (downloadable here) and definitions for more advanced scripting. This will be updated regularly. Please feel free to also drop an issue at GitHub or mail us!

NGL codepen examples

Within the NGL documentation, several examples have been made available for live testing and editing. Just have a look at the gallery, choose an example and change the .js/.ngl JavaScript file to visualize your changes.

Loading files

var files = [ "md01" "md02" ];
var promiseList = [];
files.forEach( function( name ){
	promiseList.push( stage.loadFile(
		"file://cwd/data/" + name + ".gro", {name: name} )
  );
} );
Promise.all( promiseList ).then( function( objectList ){
	var compX;
	objectList.forEach( function( comp, i ){
		if( i === 0 ){
			compX = comp;
		}else{
			comp.superpose( compX, true );
		};
		comp.addRepresentation( "cartoon" );
		comp.addTrajectory( "cwd/data/" + comp.name + ".xtc" );
	} );
} );

Within this code example, several files within a list will be loaded, superposed and trajectories will be added. The superpositioning has to be done before the trajectories are added.



//options for file loading:
stage.loadFile( "rcsb://1crn.mmtf", { * } );
* = defaultRepresentation: true, asTrajectory: true, firstModelOnly: true,
    cAlphaOnly: true, ...

Button function collection

//helper functions:
var h = scriptHelperFunctions(stage, panel);
h.components( "3SN6" )          //= stage.getComponentsByName
h.representations( "licorice" ) //= stage.getRepresentationsByName
h.visible( false, comp );
h.hide( comp );
h.show( comp );
h.superpose( comp1, comp2, * ) //* = additional options: align, sele1, sele2
h.uiText()      //= add text to panel
h.uiBreak()     //= add newline to panel
h.uiButton()    //= add button with click option to panel

Here we present a random selection of functions. For many, you might want to use the scriptHelperFunctions (here refereed as h).


h.uiButton(
    "reverse view",
    function(){
        stage.eachComponent( function( comp ){
            if (comp.visible === true){
                h.visible( false, comp );
            }else{
                h.visible( true, comp );
            }
        } );
    }
);

Hides all components/structures which are visible and shows all which are not.


h.uiButton(
    "sidechains on/off",
    function(){
        h.representations( "licorice" ).list.forEach( function( repre ){
            h.visible(!repre.visible, repre);
        } );
    }
);

Hides all licorice representations which are visible and shows all which are not. This can be easily changed for other representations or in combination with components only for specific ones.


var hidden = false;
h.uiButton(
    "show/hide all",
    function(){
        stage.eachComponent( function( comp ){
            if (hidden === true){
                h.visible(true, comp);
            }else{
                h.visible(false, comp);
            }
        } );
        if (hidden === true){
            hidden = false;
        }else{
            hidden = true;
        }
    }
);

This function hides and shows all structures.


trajectoryPlayer

Functions for embedding

//options for :
trajectoryPlayer( * );
* = basePath  + "/@md_1u19.xtc", { ... }
    "@md.xtc" //= concatenates all md.part001.xtc + md.part002.xtc + ...
Trajectory Options:
	start: 1, end: 200, step: 3, timeout: 20,
	mode: loop, interpolateType: "", 
	direction: forward, interpolateStep: 2


var isSpinning = false;
var toggleSpinning = document.getElementById( "toggleSpinning" );
toggleSpinning.addEventListener( "click", function(){
    if( !isSpinning ){
        stage.setSpin( [ 0, 1, 0.5 ], 0.01 );
        isSpinning = true;
    }else if(isSpinning){
        stage.setSpin( null, null);
        isSpinning = false;
    }
} );

This code lets the stage spin around the center with the speed of 0.01 and the tilt/angle of 0, 1 and 0.5 for x, y and z coordinates.


var toggleDownload = document.getElementById( "toggleDownload" );
toggleDownload.addEventListener( "click", function(){
    var newStructure = stage.getComponentsByName("3SN6.pdb").list[0].structure;
    var remarks = ["my new structure selection"];
    var pdbWriter = new NGL.PdbWriter( newStructure, {
        remarks: remarks
    } );
    pdbWriter.download( "TMH" );
} );

This function generates a button with a download function. It has also to be added into the html script (see the embedded scripting chapter for more an example how to do this).

Trajectory specific options

//options for adding trajectory components:
comp.addTrajectory( * );
* = basePath  + "/@md_1u19.xtc", { sele: "protein", ... }
    "@md.xtc" //= concatenates all md.part001.xtc + md.part002.xtc + ...
Trajectory Options:
	sele: "backbone and not #h", initialFrame: [int],
	centerPdb: [false|true], removePbc: [true|false],
	superpose: [true|false], defaultTimeout: [int],
	defaultStep: [int], defaultMode: ["loop"|"once"],
	defaultDirection: ["forward"|"backward"],
	defaultInterpolateStep: [int], 
	defaultInterpolateType: ["none"|"linear"|"spline"]

Brackets only for presenting the options.

Further functions

trajComp.signals.frameChanged.add(function(){
	/* manually set selection */
} )

To make selections or update e.g. text when a frame changed.


setTimeout(myfunc2, 10000);
function myfunc2(){
	stage.viewerControls.orient([
		5.16, -0.86, -8.11, 0,
		3.05, 9.11, 0.97, 0,
		7.56, -3.08, 5.15, 0,
		-28.57, -13.64, 3.36, 1
		])
}

With this workaround, the orientation is set after a certain time.


//This code selects all atoms within a certain radius and represents not only 
//this atoms but its corresponding residue.
stage.loadFile( "rcsb://3pqr" ).then( function( o ){
    // get all atoms within 5 Angstrom of retinal
    var selection = new NGL.Selection( "RET" );
    var radius = 5;
    var atomSet = o.structure.getAtomSetWithinSelection( selection,
    radius );
    // expand selection to complete groups
    var atomSet2 = o.structure.getAtomSetWithinGroup( atomSet );
    o.addRepresentation( "licorice", { sele: atomSet2.toSeleString() }
    );
    o.addRepresentation( "cartoon" );
    o.autoView();
} );

Hints

Below find some hints to get a smooth running simulation.


If you're running a simulation with an expensive representation (e.g. surface), the update might not be in time (improvements in development) - therefore set off the worker: 

comp.addRepresentation( "surface", { sele: "protein", useWorker: false } );

If you run into problems or have some specific questions, check out the Issue Tracker - MDsrv&NGL are in active development and improvement!

More

If you have any questions, found some bugs, or want to report enhancement requests use the Issue Tracker, use the contact formular or write a mail to johanna.tiemann@gmail.com or alexander.rose@weirdbyte.de.

Please give us feedback!

top