Flash API for Boosters

Please discuss on the Talk page.

 

 

General coding form

 

Accessing the applet

 

var applet = document.getElementById('maingame');

if (applet == null) return "maingame element missing";

 

from there, APIs can be used like this:

 

var ok = applet.set_sequence_string(my_seq);

 

Exploring the API without writing a booster

 

Every modern browser has some sort of console that lets users input javascript commands. 

• Open the puzzle
• Use the stamper option in the booster menu, but cancel the operation. This activates the scripting interface
• Open the javascript console of your browser, and play around

 

 

Now let's see what happens:

 

 

 

Synchronous vs Asynchronous

 

The Tsumego script is an example of a synchronous booster. Synchronous boosters have following properties:

• they do not use setTimeout() or setInterval()
• they return a simple value

 

The Naive Solver script is an example of an asynchronous booster. The features that make it asynchronous are:

• it uses setTimeout()
• the script signals asynchronicity to the applet by using the statement:
  
  return {async: "true"};
   
• the actual end of the execution is signalled by calling:
  
  applet['end_'+sid](r);
  
  where sid is the Drupal node ID of the script (here,  6713763)
• EternaScripts have timeout-checking statements automatically inserted in loops. A special statement is used in lengthy computations to prevent this global timeout (10 seconds by default) from unwanted triggering:
  global_timer = new Date();
   

 

Getters

 

get_sequence_string()

Parameters: none

Returns:

a string representing the sequence

 

 

get_full_sequence(index)

Parameters:

index: 0-based index of the state to be queried

Returns:

a string representing the full-length sequence, including the oligos in the case of a multistrand puzzle

 

 

get_locks()

Parameters: none

Returns:

a 0-based array of booleans indicating locked (true) and mutable (false) positions in the puzzle

 

 

get_targets()

Parameters: none

Returns:

an array of objects describing the structural constraints of each state in the puzzle (details to be added later)

 

 

get_native_structure(index)

Parameters:

index: 0-based index of the state to be queried

Returns:

the dot-bracket representation of the predicted MFE for the queried state in the puzzle (i.e. the native fold)

 

 

get_full_structure(index)

Parameters:

index: 0-based index of the state to be queried

Returns:

the complete dot-bracket representation of the predicted MFE, including oligos, for the queried state in the puzzle (i.e. the native fold)

 

 

get_free_energy(index)

Parameters:

index: 0-based index of the state to be queried

Returns:

the free energy of the queried state

 

 

get_tracked_indices()

Parameters: none

Returns:

an array listing the indices of the bases that have been marked with the black mark

 

 

get_barcode_indices()

Parameters: none

Returns:

an array listing the indices of the bases forming the barcode, if present in the lab puzzle

 

 

is_barcode_available()

Parameters: none

Returns:

a boolean describing whether the barcode in the puzzle is still available for the current round or not

 

 

current_folder()

Parameters: none

Returns:

the name of the currently selected folding engine (only available in labs)

 

 

check_constraints()

Parameters: none

Returns:

a boolean describing whether all constraints are fulfilled (true) or if at least one of them fails (false)

 

 

Setters

 

select_folder(folder_name)

selects a folding engine by its name

only available in lab puzzles

Parameters: 

folder_name: name of the folding engine to be used

Returns:

a boolean, true if successful, false otherwise (the operation may fail, for instance Vienna2 cannot be selected on a puzzle that contains multistrand states)

 

 

set_sequence_string(seq)

sets the sequence in the puzzle

the applet recomputes foldings, free energies and reevaluates contraints

Parameters:

seq: the sequence

Returns

a boolean, true if successful, false otherwise (the operation may fail, if seq contains invalid characters for instance)

 

 

set_tracked_indices(marks)

sets all black marks in the puzzle

Parameters:

marks: an array of indices of bases to be marked

Returns: nothing

 

 

set_design_title(design_title)

Data browser specific.

Displays a title for the current view.

Parameters:

design_title: a string containing a title/description

Returns: nothing

 

 

Folding

 

fold(seq, constraint = null)

Folds the seq sequence, eventually considering limitations defined in constraint

Parameters:

seq: a string representing the sequence to be folded

constraint: optional constraints (Vienna formatted)

Returns:

the dot-bracket representation of the MFE structure

 

 

energy_of_structure(seq, secstruct)

computes the free energy of the seq sequence folded as specified by secstruct

Parameters:

seq: the sequence

secstruct: the dot-bracket representation of the secondary structure

Return:

a floating-point number, expressed in kcal/mol

 

 

fold_with_binding_site(seq, site, bonus)

(tbd)

 

pairing_probabilities(seq, secstruct = null)

(tbd)

 

 

cofold(seq, oligo, malus = 0., constraint = null)

(tbd)

 

 

Miscellanous

 

sparks_effect(from, to)

initiates a sparking effect on the specified segment

Parameters:

from: start index

to: index of the last base

Returns: nothing