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)
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